The PYTHON_SEQUNCE tree

The classes PYTHON_SEQUENCE, PYTHON_STRING, PYTHON_LIST, and PYTHON_TUPLE allow manipulation of Python sequences of the appropriate types.

PYTHON_SEQUENCE

The base class for all Python sequences, allowing rudimentary manipulation of sequence members

class interface PYTHON_SEQUENCE
   -- base class for python sequences--strings, tuples, lists
creation
   make_from_new_reference (new_python_object_pointer: POINTER)
      -- uses the given object pointer without increasing reference 
      -- count of the python object.  Used because several Python C 
      -- api calls generate a new object with a reference count of 
      -- 1, and we don't want to increase that or we get too many 
      -- false references
      require
         new_python_object_pointer.is_not_null
   make_from_borrowed_reference (new_python_object_pointer: POINTER)
      -- uses the given object pointer and increases the reference 
      -- count of the given python object.  Used in cases where the 
      -- Python C api does not automatically increase the reference 
      -- count.  Terminology ("borrowed reference" vs "new reference") 
      -- is taken from the Python C Api documentation
      require
         new_python_object_pointer.is_not_null
   make_from_python_object (object: PYTHON_OBJECT)
      -- uses the existing python_object_pointer of python_object 
      require
         object /= Void
feature(s) from PYTHON_SEQUENCE
   length: INTEGER
      -- number of elements in the sequence
      require
         is_sequence
      ensure
         last_python_integer_result_ok;
         last_python_integer_result_ok
   concat (other: like Current): like Current
      -- the result of the current sequence appended by other
      require
         is_sequence
      ensure
         Result.reference_count = 1
   repeat (repeat_count: INTEGER): like Current
      require
         is_sequence -- this sequence repeated 'count' times
 -- this sequence repeated 'count' times
      ensure
         Result.reference_count = 1
feature(s) from PYTHON_SEQUENCE
   --  from COLLECTION
   lower: INTEGER
   upper: INTEGER
   size: INTEGER
   count: INTEGER
   item (index: INTEGER): PYTHON_OBJECT
      -- item at position index
   infix "@" (index: INTEGER): PYTHON_OBJECT
      -- item at position index
   get_slice (low, up: INTEGER): like Current
      --  create a new collection initialized with elements from range low..up
   slice (low, up: INTEGER): like Current
      --  create a new collection initialized with elements from range low..up
   put (element: like item; index: INTEGER)
      -- put element at position index
      ensure
         last_python_integer_result_ok
   remove (index: INTEGER)
      -- remove item at index; following items are shifted left by one positions
      ensure
         last_python_integer_result_ok
   set_slice (v: like item; lower_index, upper_index: INTEGER)
      -- set the slice from lower_index to upper_index with v
      ensure
         last_python_integer_result_ok
   set_slice_with (v: like item; lower_index, upper_index: INTEGER)
      -- set the slice from lower_index to upper_index with v
      ensure
         last_python_integer_result_ok
   del_slice (lower_index, upper_index: INTEGER)
      -- delete the slice from lower_index to upper_index
      ensure
         last_python_integer_result_ok
   to_tuple: PYTHON_TUPLE
      -- returns the sequence as a tuple
   count_of_value (value: like item): INTEGER
      -- returns the number of items in the collection equal to value
      ensure
         last_python_integer_result_ok
   contains (value: like item): BOOLEAN
      -- whether or not the collection contains the given value
      ensure
         last_python_integer_result_ok
   index_of (element: like item): INTEGER
      -- index of the given item.  If the item is not in the 
      -- collection, return -1 -- note that this is different from 
      -- the Eiffel library standard!
      require
         contains(element)
      ensure
         last_python_integer_result_ok
   appended_with (other: like Current): like Current
      -- returns this object appended with another sequence of the 
      -- same type
   infix "+" (other: like Current): like Current
      -- returns this object appended with another sequence of the 
      -- same type
invariant
   reference_count >= 0;
   valid_reference: not is_none implies is_sequence;
   valid_length: is_sequence implies length >= 0;
end of PYTHON_SEQUENCE

PYTHON_STRING

A class for manipulating Python strings. Note that Python strings are immutable sequences and are cached for performance reasons; the reference count of a string may be surprisingly high if it matches a string already in the cache--the Python object simply refers to the cached string

class interface PYTHON_STRING
   -- mirror to all the python string API calls--in time, will make 
   -- this conform to the Eiffel string interface
creation
   make
      -- create an empty string
   from_string (s: STRING)
      -- initialize from the characters of s, including all marshaling to 
      -- and from C strings
      ensure
         reference_count > 0 --  the above ensure clause specifies "> 0" because  python caches 
 --  strings.  The initialization of a unique string will 
 --  leave a reference count of 1, but otherwise it could be 
 --  any positive number
   from_external (p: POINTER)
      -- initialize from a C-style string... as PyString_FromString
   from_string_and_size (s: STRING; new_length: INTEGER)
      -- initialize from C-style string... as PyString_FromStringAndSize
   make_from_new_reference (new_python_object_pointer: POINTER)
      -- uses the given object pointer without increasing reference 
      -- count of the python object.  Used because several Python C 
      -- api calls generate a new object with a reference count of 
      -- 1, and we don't want to increase that or we get too many 
      -- false references
      require
         new_python_object_pointer.is_not_null
   make_from_borrowed_reference (new_python_object_pointer: POINTER)
      -- uses the given object pointer and increases the reference 
      -- count of the given python object.  Used in cases where the 
      -- Python C api does not automatically increase the reference 
      -- count.  Terminology ("borrowed reference" vs "new reference") 
      -- is taken from the Python C Api documentation
      require
         new_python_object_pointer.is_not_null
   make_from_python_object (object: PYTHON_OBJECT)
      -- uses the existing python_object_pointer of python_object 
      require
         object /= Void
feature(s) from PYTHON_STRING
   make
      -- create an empty string
   from_string (s: STRING)
      -- initialize from the characters of s, including all marshaling to 
      -- and from C strings
      ensure
         reference_count > 0 --  the above ensure clause specifies "> 0" because  python caches 
 --  strings.  The initialization of a unique string will 
 --  leave a reference count of 1, but otherwise it could be 
 --  any positive number
   from_external (p: POINTER)
      -- initialize from a C-style string... as PyString_FromString
   from_string_and_size (s: STRING; new_length: INTEGER)
      -- initialize from C-style string... as PyString_FromStringAndSize
   length: INTEGER
      -- length of the string
      require
         is_sequence
      ensure
         last_python_integer_result_ok;
         last_python_integer_result_ok;
         last_python_integer_result_ok
   to_external: POINTER
      -- C representation of the string
   to_string: STRING
      -- STRING representation
   format (args: PYTHON_OBJECT): PYTHON_OBJECT
      -- formats according to PyString_Format
invariant
   reference_count >= 0;
   valid_reference: not is_none implies is_sequence;
   valid_length: is_sequence implies length >= 0;
   valid_reference: not is_none implies is_string;
end of PYTHON_STRING

PYTHON_LIST

Python lists are analogous to Eiffel ARRAYs, allowing elements to be inserted and removed.

class interface PYTHON_LIST
   -- implementation of Python list objects
creation
   make
      -- creates an empty list
   with_capacity (new_capacity: INTEGER)
      -- creates the array with the given length
   make_from_borrowed_reference (new_python_object_pointer: POINTER)
      -- uses the given object pointer and increases the reference 
      -- count of the given python object.  Used in cases where the 
      -- Python C api does not automatically increase the reference 
      -- count.  Terminology ("borrowed reference" vs "new reference") 
      -- is taken from the Python C Api documentation
      require
         new_python_object_pointer.is_not_null
   make_from_new_reference (new_python_object_pointer: POINTER)
      -- uses the given object pointer without increasing reference 
      -- count of the python object.  Used because several Python C 
      -- api calls generate a new object with a reference count of 
      -- 1, and we don't want to increase that or we get too many 
      -- false references
      require
         new_python_object_pointer.is_not_null
   make_from_python_object (object: PYTHON_OBJECT)
      -- uses the existing python_object_pointer of python_object 
      require
         object /= Void
feature(s) from PYTHON_LIST
   --  creation   
   with_capacity (new_capacity: INTEGER)
      -- creates the array with the given length
   make
      -- creates an empty list
feature(s) from PYTHON_LIST
   -- other features
   length: INTEGER
      -- number of items in the list
      require
         is_sequence
      ensure
         last_python_integer_result_ok;
         last_python_integer_result_ok;
         last_python_integer_result_ok
   item (index: INTEGER): PYTHON_OBJECT
      -- item at the given index
   infix "@" (index: INTEGER): PYTHON_OBJECT
      -- item at the given index
   put (element: like item; index: INTEGER)
      -- put element at index
      ensure
         last_python_integer_result_ok;
         last_python_integer_result_ok
   add (element: like item; index: INTEGER)
      -- insert element at index, shifting following items right one position
      ensure
         last_python_integer_result_ok
   insert (element: like item; index: INTEGER)
      -- insert element at index, shifting following items right one position
      ensure
         last_python_integer_result_ok
   append (element: like item)
      -- add item to the end of the list
      ensure
         last_python_integer_result_ok
   add_last (element: like item)
      -- add item to the end of the list
      ensure
         last_python_integer_result_ok
   get_slice (lower_index, upper_index: INTEGER): like Current
      -- gets the slice between lower_index and upper_index
   slice (lower_index, upper_index: INTEGER): like Current
      -- gets the slice between lower_index and upper_index
   set_slice (v: like item; lower_index, upper_index: INTEGER)
      -- sets the slice with the given item v
      ensure
         last_python_integer_result_ok;
         last_python_integer_result_ok
   set_slice_with (v: like item; lower_index, upper_index: INTEGER)
      -- sets the slice with the given item v
      ensure
         last_python_integer_result_ok;
         last_python_integer_result_ok
   sort
      -- sorts the list
      ensure
         last_python_integer_result_ok
   reverse
      -- reverses the list in place
      ensure
         last_python_integer_result_ok
   to_tuple: PYTHON_TUPLE
      -- transforms the list into a tuple
invariant
   reference_count >= 0;
   valid_reference: not is_none implies is_sequence;
   valid_length: is_sequence implies length >= 0;
   valid_reference: not is_none implies is_list;
end of PYTHON_LIST

PYTHON_TUPLE

Python tuples, similar to immutable arrays, are used for passing arguments to Python functions as well as sundry other uses.

class interface PYTHON_TUPLE
creation
   make
      -- empty tuple
   with_capacity (new_length: INTEGER)
      -- creates the tuple with the given capacity
      ensure
         last_python_pointer_result_ok
   make_from_borrowed_reference (new_python_object_pointer: POINTER)
      -- uses the given object pointer and increases the reference 
      -- count of the given python object.  Used in cases where the 
      -- Python C api does not automatically increase the reference 
      -- count.  Terminology ("borrowed reference" vs "new reference") 
      -- is taken from the Python C Api documentation
      require
         new_python_object_pointer.is_not_null
   make_from_new_reference (new_python_object_pointer: POINTER)
      -- uses the given object pointer without increasing reference 
      -- count of the python object.  Used because several Python C 
      -- api calls generate a new object with a reference count of 
      -- 1, and we don't want to increase that or we get too many 
      -- false references
      require
         new_python_object_pointer.is_not_null
   make_from_python_object (object: PYTHON_OBJECT)
      -- uses the existing python_object_pointer of python_object 
      require
         object /= Void
feature(s) from PYTHON_TUPLE
   make
      -- empty tuple
   with_capacity (new_length: INTEGER)
      -- creates the tuple with the given capacity
      ensure
         last_python_pointer_result_ok
   length: INTEGER
      -- number of items in the tuple
      require
         is_sequence
      ensure
         last_python_integer_result_ok;
         last_python_integer_result_ok;
         last_python_integer_result_ok
   item (index: INTEGER): PYTHON_OBJECT
      -- item at the given index
      ensure
         last_python_pointer_result_ok
   infix "@" (index: INTEGER): PYTHON_OBJECT
      -- item at the given index
      ensure
         last_python_pointer_result_ok
   get_slice (low, up: INTEGER): like Current
      -- slice between given limits
      ensure
         last_python_pointer_result_ok
   slice (low, up: INTEGER): like Current
      -- slice between given limits
      ensure
         last_python_pointer_result_ok
   put (element: like item; index: INTEGER)
      -- sets element at index
      ensure
         last_python_integer_result_ok;
         last_python_integer_result_ok
invariant
   reference_count >= 0;
   valid_reference: not is_none implies is_sequence;
   valid_length: is_sequence implies length >= 0;
   valid_reference: not is_none implies is_tuple;
end of PYTHON_TUPLE