ada/gnatcoll-bindings
0
0
Fork 0
mirror of https://github.com/AdaCore/gnatcoll-bindings.git synced 2026-02-12 12:59:11 -08:00
Code Issues Packages Projects Releases Wiki Activity
Files
39e71d520da68cf04c09bb9daf3df49ac7e1d8d3
gnatcoll-bindings/python3/gnatcoll-python.ads
Nicolas Roche 6140ee8e69 Remove simulation of PyCObjects in Python 3.x 
Capsules should be used instead. Tentative of PyCObject simulation
cannot work as destructors associated with PyCObject and PyCapsule
do not have the same semantic (one receive the encapsulated C
pointer and the other the capsule).

This fix also memory issues in GNATCOLL.Scripts.Python

Part of T601-026

Change-Id: Id1793d255998a55b10d507deff1ce707d79a8932
2020-06-16 09:55:43 +00:00

1192 lines
50 KiB
Ada
Raw Blame History

------------------------------------------------------------------------------
-- G N A T C O L L --
-- --
-- Copyright (C) 2003-2020, AdaCore --
-- --
-- This library is free software; you can redistribute it and/or modify it --
-- under terms of the GNU General Public License as published by the Free --
-- Software Foundation; either version 3, or (at your option) any later --
-- version. This library is distributed in the hope that it will be useful, --
-- but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHAN- --
-- TABILITY or FITNESS FOR A PARTICULAR PURPOSE. --
-- --
-- As a special exception under Section 7 of GPL version 3, you are granted --
-- additional permissions described in the GCC Runtime Library Exception, --
-- version 3.1, as published by the Free Software Foundation. --
-- --
-- You should have received a copy of the GNU General Public License and --
-- a copy of the GCC Runtime Library Exception along with this program; --
-- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
-- <http://www.gnu.org/licenses/>. --
-- --
------------------------------------------------------------------------------
-- Standard interface to the python interpreter.
-- This requires at least python 3.7 to be installed on your system.
with Ada.Unchecked_Conversion;
with Interfaces.C.Strings;
with System;
package GNATCOLL.Python is
-------------
-- Objects --
-------------
type PyObject_Opaque is limited private;
type PyObject is access all PyObject_Opaque;
pragma Convention (C, PyObject);
type PyObject_Array is array (Natural range <>) of PyObject;
function Py_None return PyObject;
-- Return the python's variable Py_None, which should be returned by
-- procedures. Generally, one need to call Py_INCREF before returning this
-- value.
type PyCodeObject is new PyObject;
type PyFrameObject is new PyObject;
procedure Py_INCREF (Obj : PyObject);
procedure Py_DECREF (Obj : PyObject);
-- Increment or decrement the reference count for Obj. Obj mustn't be null
procedure Py_XINCREF (Obj : PyObject);
procedure Py_XDECREF (Obj : PyObject);
-- Same as above, but Obj can be null
procedure Print_Refcount (Obj : PyObject; Msg : String);
-- A debug procedure that prints the reference count of the object on
-- stdout.
function Get_Refcount (Obj : PyObject) return Integer;
-- Return the current reference counter for Obj. Used for debug only
function PyObject_Str (Obj : PyObject) return PyObject;
-- Compute the string representation of Obj. Returns the string
-- representation on success, NULL on failure. This is the equivalent of
-- the Python expression "str(obj)".
-- This is the equivalent of the python call str(obj), and is used by
-- python in print statements.
-- Returned value must be Py_DECREF
function PyObject_Repr (Obj : PyObject) return PyObject;
-- Similar to PyObject_Str, ie provides a displayable version of Obj. This
-- is the equivalent of the python call repr(obj), and is used by python
-- in backquotes.
-- Returned value must be Py_DECREF
function PyObject_CallMethod
(Object : PyObject; Name : String) return PyObject;
function PyObject_CallMethod
(Object : PyObject; Name : String; Arg1 : PyObject) return PyObject;
function PyObject_CallMethod
(Object : PyObject; Name : String; Arg1 : Integer) return PyObject;
-- A few examples of functions to call a method.
-- In C, the profile of this method is:
-- PyObject* PyObject_CallMethod
-- (PyObject* object, char* name, char* format, ...);
-- For instance, to call it with an object and a integer as a parameter,
-- you would use:
-- result = PyObject_CallMethod (object, "method", "(Oi)", other_obj, 1);
-- except that due to ABI differences, you need to use a C wrapper,
-- otherwise things will break on e.g. x86_64
--
-- format has the same form as in the calls to Py_BuildValue
function PyObject_Call
(Object : PyObject; Args : PyObject; Kw : PyObject) return PyObject;
-- Call a callable Python object, Object, with
-- arguments and keywords arguments. The 'args' argument can not be
-- NULL, but the 'kw' argument can be NULL.
-- The returned object must be DECREF
function PyObject_CallObject
(Object : PyObject; Args : PyObject) return PyObject;
pragma Import (C, PyObject_CallObject, "PyObject_CallObject");
-- Call a callable Python object, callable_object, with
-- arguments given by the tuple, args. If no arguments are
-- needed, then args may be NULL. Returns the result of the
-- call on success, or NULL on failure. This is the equivalent
-- of the Python expression: apply(o,args).
function PyObject_SetAttrString
(Object : PyObject;
Name : Interfaces.C.Strings.chars_ptr;
Attr : PyObject) return Integer;
pragma Import (C, PyObject_SetAttrString, "PyObject_SetAttrString");
-- Set the value of the attribute named Name, for Object, to the value
-- Attr. Returns -1 on failure. This is the equivalent of the Python
-- statement "Object.Name = Attr".
function PyObject_SetAttrString
(Obj : PyObject; Attr_Name : String; Value : PyObject) return Integer;
procedure PyObject_SetAttrString
(Obj : PyObject; Attr_Name : String; Value : PyObject);
-- Same as above
function PyObject_GenericSetAttr
(Object : PyObject;
Name : PyObject;
Attr : PyObject) return Integer;
pragma Import (C, PyObject_GenericSetAttr, "PyObject_GenericSetAttr");
-- Generic attribute setter that directly interface with the object's
-- __dict__, not with its __setattr__ method.
-- Name must be decref-ed by the caller.
function PyObject_GenericSetAttrString
(Object : PyObject;
Name : String;
Attr : PyObject) return Integer;
-- Same as above, but accepts a string as parameter
function PyObject_HasAttrString
(Obj : PyObject; Attr_Name : String) return Boolean;
-- Whether a specific attribute exists for the object
function PyObject_GetAttrString
(Object : PyObject;
Name : Interfaces.C.Strings.chars_ptr) return PyObject;
pragma Import (C, PyObject_GetAttrString, "PyObject_GetAttrString");
-- Lookup an attribute in the object's dictionnary.
-- The returned object *must* be DECREF.
function PyObject_GetAttrString
(Object : PyObject; Name : String) return PyObject;
-- Same as above.
-- The returned object must be DECREF.
function PyObject_Dir (Object : PyObject) return PyObject;
-- A list of strings for all entries in Object's dictionary..
-- The returned object must be DECREF.
function PyObject_IsTrue (Obj : PyObject) return Boolean;
-- Returns True if the object, Obj, is considered to be true, False if Obj
-- is considered to be false. This is equivalent to the Python expression:
-- "not not obj"
--------------
-- Integers --
--------------
function PyLong_FromLong (Value : Interfaces.C.long) return PyObject;
pragma Import (C, PyLong_FromLong, "PyLong_FromLong");
-- Create a new integer object from its value
function PyLong_FromSize_t (Value : Interfaces.C.size_t) return PyObject;
pragma Import (C, PyLong_FromSize_t, "PyLong_FromSize_t");
-- Create a new integer object from Value
function PyLong_AsLong (Int : PyObject) return Interfaces.C.long;
pragma Import (C, PyLong_AsLong, "PyLong_AsLong");
-- Return the value of Int.
-- Return -1 and set PyErr_Occurred if Int is not an integer object.
function PyLong_Check (Obj : PyObject) return Boolean
with Inline;
-- Returns true if the Obj is an integer object
-- Not bound: PyInt_FromString and PyInt_FromUnicode
function PyInt_FromLong (Value : Interfaces.C.long) return PyObject;
-- Create a new integer object from its value
-- Python3 removes this function. Use PyLong_FromLong instead.
function PyInt_FromSize_t (Value : Interfaces.C.size_t) return PyObject;
-- Create a new integer object from Value
-- Python3 removes this function. Use PyLong_FromSize_t instead.
function PyInt_AsLong (Int : PyObject) return Interfaces.C.long;
-- Return the value of Int.
-- Return -1 and set PyErr_Occurred if Int is not an integer object.
-- Python3 removes this function. Use PyLong_AsLong instead.
function PyInt_GetMax return Interfaces.C.long;
-- Return the maximum value an integer can have
-- Python3 removes this function. It has no PyLong equivalent.
function PyInt_Check (Obj : PyObject) return Boolean;
-- Returns true if the Obj is an integer object
-- Python3 removes this function. Use PyLong_Check instead.
------------
-- Floats --
------------
function PyFloat_AsDouble (Float : PyObject) return Interfaces.C.double;
-- Return the value of Float
function PyFloat_Check (Obj : PyObject) return Boolean;
-- Returns true if the Obj is a float object
function PyFloat_FromDouble (Value : Interfaces.C.double) return PyObject;
pragma Import (C, PyFloat_FromDouble, "PyFloat_FromDouble");
-- Creates a new float object
--------------
-- Booleans --
--------------
-- Support for the "bool" type. However, older versions of python do not
-- support this type, so you should also always check for PyInt_Check at
-- the same time
function PyBool_Check (Obj : PyObject) return Boolean;
-- Returns true if Obj is a boolean object
function PyBool_Is_True (Obj : PyObject) return Boolean;
-- Obj must return True for PyBool_Check. This function returns True if
-- obj is True.
function PyBool_FromBoolean (Value : Boolean) return PyObject;
-- Create a new boolean object
------------
-- Tuples --
------------
-- The following subprograms are in fact simple examples of importing the C
-- function in your C code, depending on your exact requirement. In C,
-- these are function with unknown number of parameters
--
-- The C function is:
-- int PyArg_ParseTuple(PyObject *arg, char *format, ...);
function PyArg_ParseTuple
(Arg : PyObject;
Format : String;
Value1 : System.Address) return Boolean;
function PyArg_ParseTuple
(Arg : PyObject;
Format : String;
Value1, Value2 : System.Address) return Boolean;
function PyArg_ParseTuple
(Arg : PyObject;
Format : String;
Value1, Value2, Value3 : System.Address) return Boolean;
function PyArg_ParseTuple
(Arg : PyObject;
Format : String;
Value1, Value2, Value3, Value4 : System.Address) return Boolean;
function PyArg_ParseTuple
(Arg : PyObject;
Format : String;
Value1, Value2, Value3, Value4, Value5 : System.Address) return Boolean;
-- Parses Format, and stores each of the tuple element in each of the
-- Values. The number of elements in Format must be the same as the number
-- of Value parameter
-- The exact description of the format should be found in the python
-- documentation.
-- Note: there is *no* type safety in these functions, but then neither is
-- there in C.
subtype PyTuple is PyObject;
function PyTuple_New (Size : Integer) return PyObject;
-- Create a new tuple that contains Size elements
function PyTuple_GetItem (Tuple : PyTuple; Index : Integer) return PyObject;
-- Get the item at a specific location in the tuple, starting at index 0.
-- Do not decref returned value.
-- See also PyObject_GetItem
procedure PyTuple_SetItem
(Tuple : PyTuple; Index : Integer; Value : PyObject);
-- Set an item in the tuple. The reference counting of Value is not
-- increased
-- See also PyObject_SetItem
function PyTuple_Size (Tuple : PyTuple) return Integer;
pragma Obsolescent (PyTuple_Size, "See PyObject_Size instead");
-- Return the size of the tuple
function Create_Tuple (Objects : PyObject_Array) return PyObject;
-- Return a new tuple made of Objects
function PyTuple_Check (Obj : PyObject) return Boolean;
-- Whether Object is a tuple
-----------
-- Lists --
-----------
function PyList_New (Size : Integer := 0) return PyObject;
-- Create a new empty list, with an initialize size
function PyList_Append (List : PyObject; Obj : PyObject) return Integer;
-- Append Obj at the end of List, and return the index of the newly
-- inserted item.
-- Increased Obj's refcount
function PyList_GetItem (List : PyObject; Index : Integer) return PyObject;
pragma Obsolescent (PyList_GetItem, "See PyObject_GetItem instead");
-- Get the item at a specific location in the list, starting at index 0.
-- Do not decref the returned value.
-- See also PyObject_GetItem.
function PyList_Size (List : PyObject) return Integer;
pragma Obsolescent (PyList_Size, "See PyObject_Size instead");
-- Return the number of items in the list
function PyList_Check (Obj : PyObject) return Boolean;
-- True if Obj is a python list
---------------
-- Iterators --
---------------
-- Iterators are an extension to list and tuples, and encapsulate both, in
-- addition to user-defined types that have a __iter__ method.
function PyIter_Check (Obj : PyObject) return Boolean;
-- True if object is an iterator (as returned by PyObject_GetIter)
function PyObject_GetIter (Obj : PyObject) return PyObject;
pragma Import (C, PyObject_GetIter, "PyObject_GetIter");
-- This is equivalent to the Python expression iter(o). It returns a new
-- iterator for the object argument, or the object itself if the object is
-- already an iterator. Raises TypeError and returns NULL if the object
-- cannot be iterated.
function PyObject_Size (Obj : PyObject) return Integer;
pragma Import (C, PyObject_Size, "PyObject_Size");
-- Return the length of object o. If the object o provides either the
-- sequence and mapping protocols, the sequence length is returned. On
-- error, -1 is returned. This is the equivalent to the Python expression
-- len(o).
function PyObject_GetItem (Obj, Key : PyObject) return PyObject;
pragma Import (C, PyObject_GetItem, "PyObject_GetItem");
-- Returns a new reference
-- Return element of o corresponding to the object key or NULL on failure.
-- This is the equivalent of the Python expression o[key].
function PyObject_GetItem (Obj : PyObject; Key : Integer) return PyObject;
-- A special case where the key is an integer
function PyObject_SetItem (Obj, Key, Value : PyObject) return Integer;
pragma Import (C, PyObject_SetItem, "PyObject_SetItem");
-- Map the object key to the value v. Returns -1 on failure. This is the
-- equivalent of the Python statement o[key] = v.
procedure PyObject_SetItem
(Obj : PyObject; Key : Integer; Value : PyObject);
-- A special case where the key is an integer
function PyIter_Next (Obj : PyObject) return PyObject;
pragma Import (C, PyIter_Next, "PyIter_Next");
-- Return the next value from the iteration o. If the object is an
-- iterator, this retrieves the next value from the iteration, and returns
-- NULL with no exception set if there are no remaining items. If the
-- object is not an iterator, TypeError is raised, or if there is an error
-- in retrieving the item, returns NULL and passes along the exception.
--
-- To write a loop which iterates over an iterator, the code should look
-- something like this:
--
-- Iterator : PyObject := PyObject_GetIter (Obj);
-- Item : PyObject;
--
-- if Iterator = null then
-- -- propagate error
-- else
-- loop
-- Item := PyIter_Next (Iterator);
-- exit when Item = null;
--
-- Py_DECREF (Item);
-- end loop;
--
-- Py_DECREF (Iterator);
-- end if;
-------------
-- Strings --
-------------
function PyBaseString_Check (Obj : PyObject) return Boolean;
-- Returns True if Obj is either a string or a unicode object
function PyString_Check (Obj : PyObject) return Boolean;
-- Returns true if the Obj is a string object
function PyString_AsString (Str : PyObject) return String;
-- Same as above, higher-level
function PyString_FromString (Str : String) return PyObject;
-- Return a python object representing Str
function PyUnicode_Check (Obj : PyObject) return Boolean;
function PyUnicode_FromString (Str : String) return PyObject;
-- A Unicode string, from a latin-1 encoded Ada string
function Unicode_AsString
(Str : PyObject; Encoding : String := "utf-8") return String;
-- Return an encoded version of Str.
-- This is not a function from python, but a wrapper around
-- PyUnicode_AsEncodedString and PyString_AsString.
-- In case of encoding error, characters are replaced with '?'
type Unicode_Error_Handling is (Strict, Ignore, Replace);
-- How encoding errors are treated for unicode objects
-- Strict: raise a ValueError
-- Ignore: ignore the wrong characters, which are skipped
-- Replace: replace illegal characters with '?'
function PyUnicode_AsEncodedString
(Unicode : PyObject; -- A unicode object
Encoding : String; -- The encoding
Errors : Unicode_Error_Handling := Strict) -- Error handling
return PyObject;
-- Encodes a Unicode object and returns the result as Python string object.
-- You can use PyString_AsString to get the corresponding Ada string.
-------------
-- Modules --
-------------
function PyImport_AddModule (Module_Name : String) return PyObject;
-- Return the module object corresponding to a module name. The name
-- argument may be of the form package.module. First check the modules
-- dictionary if there's one there, and if not, create a new one and insert
-- in in the modules dictionary. Because the former action is most common,
-- this does not return a new reference, and you do not own the returned
-- reference.
--
-- Warning: this function does not load or import the module; if the module
-- wasn't already loaded, you will get an empty module object. Use
-- PyImport_ImportModule() or one of its variants to import a module.
-- Return NULL with an exception set on failure.
function PyImport_ImportModule (Module_Name : String) return PyObject;
-- Import a new module in the interpreter
function PyImport_Import (Name : PyObject) return PyObject;
pragma Import (C, PyImport_Import, "PyImport_Import");
-- Higher-level import emulator which emulates the "import" statement
-- more accurately -- it invokes the __import__() function from the
-- builtins of the current globals. This means that the import is
-- done using whatever import hooks are installed in the current
-- environment, e.g. by "rexec".
-- A dummy list ["__doc__"] is passed as the 4th argument so that
-- e.g. PyImport_Import(PyString_FromString("win32com.client.gencache"))
-- will return <module "gencache"> instead of <module "win32com">. */
function PyModule_GetDict (Module : PyObject) return PyObject;
-- Return the dictionary object that implements module's namespace; this
-- object is the same as the __dict__ attribute of the module object. This
-- function never fails.
-- It is recommended that you use the other PyModule_* subprograms rather
-- than manipulate this dictionnary directly.
-- The returned dictionary is a borrow reference, so you shouldn't
-- Py_DECREF it.
function PyModule_New (Module_Name : String) return PyObject;
-- Create a new module.
-- Use the PyModule_GetDic function to add new objects to the module, or
-- better use PyModule_AddObject.
function PyModule_AddObject
(Module : PyObject;
Name : Interfaces.C.Strings.chars_ptr;
Object : PyObject) return Integer;
pragma Import (C, PyModule_AddObject, "PyModule_AddObject");
-- Add a new object to the module's directory. Object can be a subprogram,
-- integer, ... Do not Py_DECREF Object afterward, this is only a borrowed
-- reference.
-- Return 0 in case of success, -1 in case of error.
-- Name can be freed immediately by the caller
function PyModule_AddObject
(Module : PyObject; Name : String; Object : PyObject) return Integer;
-- Same as above
function PyModule_Getname (Module : PyObject) return String;
-- Return the name of the module
----------------------------------
-- Creating modules and methods --
----------------------------------
type Argument_Methods is mod 2 ** Integer'Size;
METH_VARGS : constant Argument_Methods := 16#0001#;
METH_KEYWORDS : constant Argument_Methods := 16#0002#;
METH_NOARGS : constant Argument_Methods := 16#0004#;
METH_CLASS : constant Argument_Methods := 16#0010#;
METH_STATIC : constant Argument_Methods := 16#0020#;
-- How arguments are passed to callbacks:
-- - METH_VARGS: only positional arguments in the form of a tuple are
-- accepted
-- - "METH_VARGS or METH_KEYWORDS": a function accepting keyword
-- arguments.
-- - METH_CLASS and METH_STATIC can only be used for class methods, not
-- for module methods. They both indicate that a method is a class-wide
-- method. They are callable from the class or an instance, but the
-- instance is ignored and not passed as a parameter.
type C_Method_Vargs is access function
(Self : PyObject; Args : PyObject) return PyObject;
pragma Convention (C, C_Method_Vargs);
-- A callback for a METH_VARGS method.
-- The first argument is the object on which the method is applied, or null
-- if this is a standard function.
-- The second argument is a tuple of the parameters. They can be extracted
-- through a call to PyArg_ParseTuple.
type C_Method_Keywords is access function
(Self : PyObject; Args : PyObject; Kwargs : PyObject) return PyObject;
pragma Convention (C, C_Method_Keywords);
-- A callback for a METH_KEYWORDS method.
-- The first argument is the object on which the method is applied, or null
-- if this is a standard function.
-- The second argument is a tuple of the positional parameters.
-- The third argument is a hash table of the named parameters.
-- Parameters can be extracted through a call to
-- PyArg_ParseTupleAndKeywords.
type C_Callback_Record is private;
type C_Callback is access C_Callback_Record;
pragma Convention (C, C_Callback);
-- The exact type doesn't matter, we only want to cover all possible cases
-- of callbacks (C_Method_Vargs, C_Method_Keywords)
function To_Callback is new Standard.Ada.Unchecked_Conversion
(C_Method_Vargs, C_Callback);
function To_Callback is new Standard.Ada.Unchecked_Conversion
(C_Method_Keywords, C_Callback);
type PyMethodDef is record
Name : Interfaces.C.Strings.chars_ptr;
Func : C_Callback;
Flags : Argument_Methods;
Doc : Interfaces.C.Strings.chars_ptr;
end record;
pragma Convention (C, PyMethodDef);
-- Definition for one of the methods of an object.
-- Name is the name used in the python interpreter to reference the method
-- (one would use the syntax self.Name (...))
-- Func is the callback in the Ada code that should be called when the
-- method is invoked.
-- Flags indicates how the arguments should be passed.
-- Doc is the optional documentation string for the method
No_MethodDef : constant PyMethodDef;
type PyMethodDef_Array is array (Natural range <>) of PyMethodDef;
pragma Convention (C, PyMethodDef_Array);
-- The full list of methods supported by a type.
-- You do not need to terminate this array by a null element, as is done in
-- C. This is automatically taken care of by Ada.
No_MethodDef_Array : constant PyMethodDef_Array;
procedure Free (Method : in out PyMethodDef);
procedure Free (Methods : in out PyMethodDef_Array);
-- Free the memory occupied by Method
function Py_InitModule
(Module_Name : String;
Methods : PyMethodDef_Array := No_MethodDef_Array;
Doc : String := "") return PyObject;
-- Create and initialize a new module, with a set of predefined methods.
-- Do not free Methods while the module is in use.
-- The module is not visible in the interpreter until you have done a
-- "import MODULE_NAME" in the interpreter.
--
-- The first parameter to the methods declared in Methods will be null.
procedure Add_Function
(Module : PyObject; Func : PyMethodDef; Self : PyObject := null);
-- Add a new function to Module.
-- Do not free Func while this function is registered.
-- The first parameter to Func will be Self (defaults to Module if Self is
-- null).
------------------
-- Dictionaries --
------------------
-- Dictionaries are hash tables, used internally by python to associate
-- functions with modules or methods with objects.
-- See PyModule_GetDict to see how to get the dictionary from a module.
subtype PyDictObject is PyObject;
function PyDict_Check (Obj : PyObject) return Boolean;
-- Return True if Obj is a dict object or an instance of a subtype of the
-- dict type.
function PyDict_New return PyDictObject;
-- Create a new empty dictionary
function PyDict_Contains
(Dict : PyDictObject; Key : PyObject) return Boolean;
-- Determine if dictionary contains key
function PyDict_SetItemString
(Dict : PyDictObject;
Key : Interfaces.C.Strings.chars_ptr;
Obj : PyObject) return Integer;
pragma Import (C, PyDict_SetItemString, "PyDict_SetItemString");
-- Store a new object in Dict. Obj should be Py_DECREF after the call.
-- Return 0 if all went well, -1 otherwise
-- Key should be deallocated.
procedure PyDict_SetItemString
(Dict : PyDictObject; Key : String; Obj : PyObject);
-- Same as above. Refcounting for Obj is automatically increased, you do
-- not need to do it yourself.
function PyDict_SetItem
(Dict : PyDictObject;
Key : PyObject;
Value : PyObject) return Integer;
-- Add a new item to the dictionary.
-- Key and Value should be Py_DECREF'ed after this call.
-- Return 0 if all went well, -1 otherwise
function PyDict_GetItemString
(Dict : PyDictObject;
Key : Interfaces.C.Strings.chars_ptr) return PyObject;
pragma Import (C, PyDict_GetItemString, "PyDict_GetItemString");
-- Get an object from a dictionary. Do not decref the returned value
function PyDict_GetItemString
(Dict : PyDictObject; Key : String) return PyObject;
-- Same as above
function PyDict_GetItem
(Dict : PyDictObject; Key : PyObject) return PyObject;
-- Same as above
procedure PyDict_Next
(Dict : PyObject;
Pos : in out Integer;
Key : out PyObject;
Value : out PyObject);
-- Starting with Pos = 0, this traverses all items in Dict.
-- When there are no more items, Pos is set to -1.
-- It isn't safe to use this in a loop that modifies Dict.
function PyDict_Size (Dict : PyObject) return Integer;
-- Return the number of elements in Dict
----------
-- Sets --
----------
-- A set object is an unordered collection of distinct hashable objects.
-- Common uses include membership testing, removing duplicates from a
-- sequence, and computing mathematical operations such as intersection,
-- union, difference, and symmetric difference.
function PyAnySet_Check (Obj : PyObject) return Boolean;
-- Return true if p is a set object, a frozenset object, or an instance of
-- a subtype.
---------------
-- Functions --
---------------
function PyFunction_Check (Func : PyObject) return Boolean;
-- Whether Func is a function object
function PyFunction_Get_Code (Func : PyObject) return PyCodeObject;
-- Return the code of the function (see PyEval_EvalCodeEx).
-- Refcount for the code is not increased.
function PyFunction_Get_Globals (Func : PyObject) return PyObject;
-- Return the globals dictionary the function belongs to
function PyFunction_Get_Defaults (Func : PyObject) return PyObject;
-- Return a tuple of the default values for all the parameters of Func
function PyFunction_Get_Closure (Func : PyObject) return PyObject;
-- ???
function PyCallable_Check (Func : PyObject) return Boolean;
-- Determine if the object o is callable. This function always succeeds
------------------
-- Object types --
------------------
subtype PyTypeObject is PyObject;
-- The internal structure that describes a Python type (and all the default
-- primitive subprograms like __getattr__, __setattr__, ...
function Py_TYPE (Obj : PyObject) return PyTypeObject;
-- Return the type object of a given object.
function Name (Obj : PyTypeObject) return String;
-- Name of type, useful for printing, in format "<module>.<name>"
function Type_New
(Name : String;
Bases : PyTuple;
Dict : PyObject;
Metatype : PyTypeObject := null) return PyObject;
-- Creates a so called new-style class in python.
-- Such classes have a metaclass (ie their type) that is "type" or one of
-- its ancestors. Their provide a number of advantages over older classes:
-- - it is possible to extend builtin types such as "list" or "tuple"
-- - support for the "super" function, to provide collaborative multiple
-- inheritance
-- - support for properties (ie fields manipulated through setters and
-- getters)
-- - better Method Resolution Order, more compatible with multiple
-- inheritance.
-- See the original paper at
-- http://www.python.org/download/releases/2.2.3/descrintro
--
-- This replaces the older PyClass_New.
-- This isn't a standard python function, but is specific to Ada. If the
-- Metatype is not specified, it will default to "type", although depending
-- on the list of base classes you provide, python might decide to use
-- another metaclass.
-- This function is similar to calling the "type()" function from within
-- python:
-- A = type ("Name", (list,), {});
-- which creates a new class Name deriving from "list".
--
-- Dict can contain any number of things (including for instance the list
-- of methods for the class, although you can add some later), just as if
-- you were defining the class in Python:
-- - "__slots__"
-- - "__module__" (although that is set automatically otherwise)
-- - "__doc__"
function PyObject_IsInstance
(Inst : PyObject; Cls : PyObject) return Boolean;
-- Return if the metaclass of Inst is Cls (ie Inst was created with
-- something like "Inst = Cls (...)"
----------------
-- Exceptions --
----------------
procedure PyErr_Print;
-- Print the current exception and its traceback to sys.stderr.
-- This also clears the error indicator.
-- Call this procedure only if the error indicator is set
procedure PyErr_SetInterrupt;
-- Interrupt the current command in the interpreter. This is the equivalent
-- of Control-C in a terminal executing python.
procedure PyErr_Fetch
(EType : out PyObject;
Occurrence : out PyObject;
Traceback : out PyObject);
-- Get the current exception information.
-- Occurrence is a tuple, made of the following information:
-- (msg, ('input_stream_name', line, column, input_text))
-- where msg is the exception's message, and the second tuple is the
-- location where the exception occurred.
-- EType is the type of the exception, like "exceptions.SyntaxError".
--
-- This calls clears the current exception. If you want to call PyErr_Print
-- later on, you will need to call PyErr_Restore with the same parameters
-- to restore the current exception.
procedure PyErr_NormalizeException
(EType : in out PyObject;
Occurrence : in out PyObject;
Traceback : in out PyObject);
-- Normalize a raised exception. This generally needs to be called after
-- PyErr_Fetch.
-- This ensure that if EType is an class, Occurrence is an instance.
procedure PyErr_Restore
(EType : PyObject;
Occurrence : PyObject;
Traceback : PyObject);
-- Set the current exception
procedure PyErr_Clear;
-- Clear the current exception. This must be called at the end of your
-- exception handlers, although it is called automatically by PyErr_Print
procedure PyErr_BadArgument;
-- Set the current exception as a "bad argument" exception. The function
-- should also return null to its caller.
function PyErr_NewException
(Name : String; Base : PyObject := null; Dict : PyObject := null)
return PyObject;
-- Create a new exception, which can then be raised by:
-- - calling PyErr_SetString (Except, "message");
-- - returning null from your subprogram
-- Name must be of the form "module.name"
procedure PyErr_SetString (Except : PyObject; Msg : String);
-- Raise Except, and associate it with a specific message
---------
-- Sys --
---------
procedure PySys_SetObject (Name : String; Object : PyObject);
-- Set one of the predefined objects in the python interpreter. See the
-- module "sys".
-- Among these objects are:
-- - "stdin", "stdout", "stderr": standard file objects
-- - "_stdin", _stdout", "_stderr": initial values for standard files
-- - "modules": dictionary of modules
-- - "path": module search path
-- - "ps1", "ps2": prompts
-- - "displayhook": ???
-- - "excepthook": ???
function PySys_GetObject (Name : String) return PyObject;
-- Return an object from the sys module,
-- Returned object must not be Py_DECREF by the caller.
-----------
-- Files --
-----------
function PyFile_WriteString (Text : String; File : PyObject) return Boolean;
-- Write a string to an instance of file. You can for instance get such an
-- instance by using
-- PySys_GetObject ("stdout")
-- Return False if the string couldn't be written
function PyFile_FromString (File_Name, Mode : String) return PyObject;
-- Create an instance of file.
-- Python3 removes this function. Use "io.open()" instead.
-----------------
-- Class types --
-----------------
function Lookup_Object (Module : String; Name : String) return PyObject;
function Lookup_Object (Module : PyObject; Name : String) return PyObject;
-- Lookup an object in the module.
-- Typical use is
-- Obj := Lookup_Class_Object ("__builtin__", "file");
-- null is returned if the class is not found.
-- The second version is slightly faster and should be used when you
-- already have a handle to the module
procedure Add_Method
(Class : PyObject; Func : PyMethodDef; Self : PyObject := null;
Module : PyObject);
-- Add a new method to the class.
-- The method is an instance method.
-- When the method is called from the python interpreter, its Self argument
-- is set to the value of Self.
-- Its first argument will always be the instance itself. Therefore the
-- first character in the argument to PyArg_ParseTuple should be "O".
procedure Add_Static_Method
(Class : PyObject; Func : PyMethodDef; Self : PyObject := null;
Module : PyObject);
-- Return a static version of Method. This method doesn't receive an
-- instance or the class as its first parameter. This is similar to C++ or
-- Java's static methods.
-- If no documentation is set for the method, it will be set to the fully
-- qualified name of the method, since otherwise there is no way from the
-- GPS shell to get access to the class to which the method belongs.
procedure Add_Class_Method
(Class : PyObject; Func : PyMethodDef; Module : PyObject);
-- Return a class version of Method.
-- This is a method that receives the class as implicit first argument,
-- just like an instance method receives the instance.
-- It can be called either on the class or an instance. If a class method
-- is called for a derived class, the derived class object is passed as the
-- implied first argument.
-- If no documentation is set for the method, it will be set to the fully
-- qualified name of the method, since otherwise there is no way from the
-- GPS shell to get access to the class to which the method belongs.
function Py_IsSubclass (Class : PyObject; Base : PyObject) return Boolean;
-- True if Class is a subclass of Base (or Base itself)
function PyMethod_Check (Obj : PyObject) return Boolean;
-- Whether Obj is a method of a class
function PyMethod_Self (Obj : PyObject) return PyObject;
-- Return the instance with which the method is bound. This might be null
-- if we have an unbound class method (Class.method), or non-null if we
-- have a bound class method (the result of self.method)
-- Returns a borrowed reference, no need to Py_DECREF
function PyMethod_Function (Obj : PyObject) return PyObject;
-- Return the function object associated with the method. That is the code
-- that is actually executed when the method is called
-----------------
-- Descriptors --
-----------------
-- Descriptors are an advanced feature of python, used as the underlying
-- capability for bounded methods, properties,...
-- Basically, when a field in an instance is a descriptor, its value is
-- read from a Getter, instead of directly. Likewise it is set through a
-- Setter.
type C_Getter is access function
(Obj : PyObject; Closure : System.Address) return PyObject;
pragma Convention (C, C_Getter);
type C_Setter is access function
(Obj : PyObject;
Prop : PyObject;
Closure : System.Address) return Integer;
pragma Convention (C, C_Setter);
-- Closure is some custom data you have specified in the call to
-- Create_GetSetDef
function PyDescr_NewGetSet
(Typ : PyObject;
Name : String;
Setter : C_Setter := null;
Getter : C_Getter := null;
Doc : String := "";
Closure : System.Address := System.Null_Address) return Boolean;
-- Register a new property (accessed through setters and getters) in the
-- specified Typ. The property is immediately added to the dictionary.
-- False is returned if the property could not be added.
-- The Closure will be passed as is to Setter and Getter.
------------------------------------
-- Creating and declaring methods --
------------------------------------
function Create_Method_Def
(Name : String;
Func : C_Method_Vargs;
Doc : String := "")
return PyMethodDef;
-- Convenience function to create method definitions.
-- See the description of the parameters in the declaration of PyMethodDef
-- The flags are automatically set to METH_VARGS, which is the appropriate
-- type for callbacks of this form.
-- The returned value must be freed by the caller.
function Create_Method_Def
(Name : String;
Func : C_Method_Keywords;
Doc : String := "")
return PyMethodDef;
-- Same as above, for methods accepting keywords.
-- The returned value must be freed by the caller
------------------------
-- Executing commands --
------------------------
function PyRun_SimpleString (Cmd : String) return Boolean;
-- Executes Cmd in the __main__ module.
-- Return True on success, False if an exception occurred (it is your
-- responsibility to check the current exception)
type Interpreter_State is private;
Py_Single_Input : constant Interpreter_State;
Py_File_Input : constant Interpreter_State;
Py_Eval_Input : constant Interpreter_State;
-- The state of the interpreter when evaluating a string.
-- - Single_Input: evaluate any command in the interpreter. This will
-- print the result (but return None)
-- - Eval_Input: evaluate an expression. Evaluates an expression.
-- Equivalent to 'eval'.
-- - File_Input: evaluate a whole file, and return None.
-- Equivalent to 'exec'.
function PyRun_String
(Str : String;
Start : Interpreter_State;
Globals : PyObject;
Locals : PyObject) return PyObject;
-- Execute Python source code from str in the context specified by the
-- dictionaries globals and locals. The parameter start specifies the
-- start token that should be used to parse the source code.
--
-- Returns NULL if an exception occurred, None otherwise.
function Py_CompileString
(Cmd : String; Name : String; State : Interpreter_State)
return PyCodeObject;
-- Compile Cmd into a code object. Null is returned if Cmd couldn't be
-- compiled, either because of a syntax error or because Cmd is incomplete
function PyEval_GetGlobals return PyObject;
pragma Import (C, PyEval_GetGlobals, "PyEval_GetGlobals");
-- Return the dictionary for global variables
function PyEval_EvalCode
(Code : PyCodeObject;
Globals : PyObject;
Locals : PyObject) return PyObject;
-- Evaluate a precompiled code object
function PyEval_EvalCodeEx
(Code : PyCodeObject;
Globals : PyObject;
Locals : PyObject;
Args : PyTuple := null;
Kwds : PyDictObject := null;
Defaults : PyTuple := null;
Closure : PyObject := null) return PyObject;
-- Evaluate a precompiled code object. This is mostly used to execute a
-- function (get its code with PyFunction_Get_Code), specifying some of
-- the parameters
--------------------------------------
-- Evaluating and Tracing execution --
--------------------------------------
-- Python will periodically call two functions that you can register: a
-- profile function, called every time a subprogram is called or returns,
-- and a trace function called for every instruction.
-- These can be used to trace the execution of your program, but also to
-- interrupt a parser embedded in your application:
-- - register a trace function, and every n calls, check for gtk events
-- and call PyErr_SetInterrupt if necessary
-- - a profile function would not be called for an infinite loop that
-- never calls another subprogram, so is not appropriate for for such
-- usage.
-- There is still a catch: you will not be able to interrupt a long sleep()
-- operation with this method, since the interpret itself is paused. The
-- best solution to handle this is to have your own Control-C handler,
-- although the user would have to type this in the terminal used to start
-- your application.
type Why_Trace_Func is private;
PyTrace_Call : constant Why_Trace_Func;
PyTrace_Exception : constant Why_Trace_Func;
PyTrace_Line : constant Why_Trace_Func;
PyTrace_Return : constant Why_Trace_Func;
PyTrace_C_Call : constant Why_Trace_Func;
PyTrace_C_Exception : constant Why_Trace_Func;
PyTrace_C_Return : constant Why_Trace_Func;
type Py_Trace_Func is access function
(User_Arg : PyObject;
Frame : PyFrameObject;
Why : Why_Trace_Func;
Object : PyObject) return Integer;
-- Return 0 in case of success, or -1 if an exception is raised.
-- Objects's value depends on the type of callback. For PyTrace_Return,
-- this is the returned value. For PyTrace_Exception, this is the
-- exception. PyTrace_Line is called for all instructions, but only for
-- the trace function, not the profile function.
procedure PyEval_SetProfile (Proc : Py_Trace_Func; User_Arg : PyObject);
-- Register a new profiling function
procedure PyEval_SetTrace (Proc : Py_Trace_Func; User_Arg : PyObject);
-- Register a new tracing function
function PyFrame_GetLineNumber (Frame : PyFrameObject) return Integer;
-- Return the line number that frame is currently executing.
function PyFrame_Get_Code (Frame : PyFrameObject) return PyCodeObject;
-- Return code object associated with the frame.
-- Returns a borrowed reference, no need to Py_DECREF
function PyCode_Get_Filename (Code : PyCodeObject) return PyObject;
-- Return file name of the code object.
-- Returns a borrowed reference, no need to Py_DECREF
function PyCode_Get_Name (Code : PyCodeObject) return PyObject;
-- Return function name of the code object.
-- Returns a borrowed reference, no need to Py_DECREF
function PyFrame_Get_Back (Frame : PyFrameObject) return PyFrameObject;
-- Return previous frame in stack.
-- Returns a borrowed reference, no need to Py_DECREF
-------------
-- Threads --
-------------
type PyThreadState_Opaque is limited private;
type PyThreadState is access all PyThreadState_Opaque;
private
type PyObject_Opaque is null record;
type PyThreadState_Opaque is null record;
type Interpreter_State is new Integer;
Py_Single_Input : constant Interpreter_State := 256;
Py_File_Input : constant Interpreter_State := 257;
Py_Eval_Input : constant Interpreter_State := 258;
-- Values are copied from Python.h, and must be synchronized. They will
-- probably never change, though, so this should be safe.
type Why_Trace_Func is new Integer;
PyTrace_Call : constant Why_Trace_Func := 0;
PyTrace_Exception : constant Why_Trace_Func := 1;
PyTrace_Line : constant Why_Trace_Func := 2;
PyTrace_Return : constant Why_Trace_Func := 3;
PyTrace_C_Call : constant Why_Trace_Func := 4;
PyTrace_C_Exception : constant Why_Trace_Func := 5;
PyTrace_C_Return : constant Why_Trace_Func := 6;
type C_Callback_Record is new Integer; -- whatever
No_MethodDef : constant PyMethodDef :=
(Interfaces.C.Strings.Null_Ptr, null, 0,
Interfaces.C.Strings.Null_Ptr);
No_MethodDef_Array : constant PyMethodDef_Array := (1 .. 0 => No_MethodDef);
pragma Convention (C, Py_Trace_Func);
pragma Import (C, PyDict_New, "PyDict_New");
pragma Import (C, PyEval_SetProfile, "PyEval_SetProfile");
pragma Import (C, PyEval_SetTrace, "PyEval_SetTrace");
pragma Inline (PyImport_AddModule);
pragma Inline (PyRun_SimpleString);
pragma Inline (PyArg_ParseTuple);
pragma Inline (PyString_Check);
pragma Inline (PyUnicode_Check);
pragma Inline (PyInt_Check);
pragma Inline (PyFloat_Check);
pragma Import (C, PyModule_GetDict, "PyModule_GetDict");
pragma Import (C, Py_INCREF, "ada_py_incref");
pragma Import (C, Py_DECREF, "ada_py_decref");
pragma Import (C, Py_XINCREF, "ada_py_xincref");
pragma Import (C, Py_XDECREF, "ada_py_xdecref");
pragma Import (C, PyErr_Print, "PyErr_Print");
pragma Import (C, PyObject_Str, "PyObject_Str");
pragma Import (C, PyObject_Call, "PyObject_Call");
pragma Import (C, PyEval_EvalCode, "PyEval_EvalCode");
pragma Import (C, PyEval_EvalCodeEx, "ada_PyEval_EvalCodeEx");
pragma Import (C, PyErr_SetInterrupt, "PyErr_SetInterrupt");
pragma Import (C, PyTuple_New, "PyTuple_New");
pragma Import (C, PyTuple_GetItem, "PyTuple_GetItem");
pragma Import (C, PyTuple_SetItem, "PyTuple_SetItem");
pragma Import (C, Py_None, "ada_py_none");
pragma Import (C, PyErr_Clear, "PyErr_Clear");
pragma Import (C, PyErr_Fetch, "PyErr_Fetch");
pragma Import (C, PyTuple_Size, "PyTuple_Size");
pragma Import (C, PyInt_FromLong, "PyInt_FromLong");
pragma Import (C, PyInt_FromSize_t, "PyInt_FromSize_t");
pragma Import (C, PyInt_AsLong, "PyInt_AsLong");
pragma Import (C, PyFloat_AsDouble, "PyFloat_AsDouble");
pragma Import (C, PyInt_GetMax, "PyInt_GetMax");
pragma Import (C, PyList_New, "PyList_New");
pragma Import (C, PyList_Append, "PyList_Append");
pragma Import (C, PyErr_BadArgument, "PyErr_BadArgument");
pragma Import (C, PyErr_NormalizeException, "PyErr_NormalizeException");
pragma Import (C, PyObject_Dir, "PyObject_Dir");
pragma Import (C, PyObject_Repr, "PyObject_Repr");
pragma Import (C, PyErr_Restore, "PyErr_Restore");
pragma Import (C, PyDict_Size, "PyDict_Size");
pragma Import (C, PyList_GetItem, "PyList_GetItem");
pragma Import (C, PyList_Size, "PyList_Size");
pragma Import (C, PyDict_SetItem, "PyDict_SetItem");
pragma Import (C, PyDict_GetItem, "PyDict_GetItem");
pragma Import (C, Get_Refcount, "ada_pyget_refcount");
pragma Import (C, PyFunction_Get_Code, "ada_pyfunction_get_code");
pragma Import (C, PyFunction_Get_Globals, "ada_pyfunction_get_globals");
pragma Import (C, PyFunction_Get_Closure, "ada_pyfunction_get_closure");
pragma Import (C, PyFunction_Get_Defaults, "ada_pyfunction_get_defaults");
pragma Import (C, PyMethod_Function, "PyMethod_Function");
pragma Import (C, PyMethod_Self, "PyMethod_Self");
pragma Import (C, PyFrame_GetLineNumber, "PyFrame_GetLineNumber");
pragma Import (C, PyFrame_Get_Code, "ada_pyframe_get_code");
pragma Import (C, PyFrame_Get_Back, "ada_pyframe_get_back");
pragma Import (C, PyCode_Get_Filename, "ada_pycode_get_filename");
pragma Import (C, PyCode_Get_Name, "ada_pycode_get_name");
pragma Import (C, Py_TYPE, "__gnatcoll_py_type");
end GNATCOLL.Python;
Reference in New Issue View Git Blame Copy Permalink