reahl.ptongue package

class reahl.ptongue.GemObject(session, oop)[source]

Bases: object

A Python object that represents a given object in a Gem.

This class serves as a bridge between Python code and Gemstone objects. Each instance wraps a reference to an object in a Gemstone session and provides methods to interact with that object.

A GemObject forwards method calls to its counterpart in the Gem. It returns other GemObject objects (and if the method takes arguments, those must also be GemObject objects):

today = date_class.today()
assert isinstance(today, GemObject)
assert today.is_kind_of(date_class)

In Python, method names are spelled differently. Each ‘:’ in a Smalltalk method symbol is replaced with a ‘_’ in Python. When calling such a method, you must pass the correct number of arguments as Python positional arguments:

user_globals.at_put(some_key, gem_number)
Variables:

  • oop – The object-oriented pointer value in the Gemstone VM.

  • session – Reference to the session this object belongs to.

Parameters:

  • session – The Gemstone session this object belongs to.

  • oop – The object-oriented pointer value in the Gemstone VM.

__iter__()[source]

Provide iteration over collection objects.

This allows Gemstone collections to be iterated over using Python’s iteration protocol.

It works by first calling self.asOrderedCollection in Gemstone - something that may have performance implications depending on the situation.

Yield:

Each element in the collection.

__str__()[source]

Provide a human-readable string representation.

This method attempts to create a readable representation of the Gemstone object, similar to how it would be displayed in Gemstone using printString.

Returns:

A human-readable string representation of the object.

gemstone_class()[source]

Get the Gemstone class of this object.

Returns:

A GemObject representing the class of this object.

is_kind_of(a_class)[source]

Check if this object is an instance of the given class or one of its subclasses.

Parameters:

a_class – A Gemstone class object to check against.

Returns:

True if this object is an instance of the given class or a subclass, False otherwise.

property is_nil

Check if this object is Gemstone’s nil.

Returns:

True if this object is nil, False otherwise.

property is_symbol

Check if this object is a Gemstone Symbol.

Returns:

True if this object is a Symbol, False otherwise.

perform(selector, *args)[source]

Directly perform a method on the Gemstone object.

This is the low-level method that executes a method call on the Gemstone object. It accepts a Gemstone selector and arguments.

This method need not be called directly, it is usually automatically invoked when an unknown attribute is called on a GemObject, for example:

session.Date.today().addDays(2)
Parameters:

  • selector – The method selector, either as a GemObject Symbol or a string that will be converted to a Symbol.

  • args – GemObject arguments to pass to the method. If not a GemObject, the object will be transformed using session.from_py()

Returns:

The result of the method call.

property to_py

Convert this GemObject to an appropriate Python object.

This method transfers the GemObject to a Python object of appropriate type. Apart from a few collections, this only supports basic types, such as unicode strings, various numbers and booleans.

Collections supported:

  • OrderedCollection - becomes a Python list

  • Dictionary - becomes a Python dict

  • IdentitySet - becomes a Python set

In the case of collections, the contents of the new collections on the Python side are created using object.to_py individually on the Gemstone elements contained inside the Gemstone collections.

Returns:

A Python representation of this Gemstone object.

Raises:

NotSupported – If the object cannot be converted to a Python type.

class reahl.ptongue.GemstoneSession[source]

Bases: object

A Python interface for managing a connection to a Gemstone database.

This class provides the foundation for interacting with Gemstone objects from Python. It manages conversion between Python and Gemstone objects, caches Gemstone objects to maintain identity, and handles object lifecycle management.

The session maintains a cache of GemObject instances to ensure that the same Gemstone object is always represented by the same Python object during its lifetime.

GemstoneSession is not intended to be instantiated directly, its subclasses are: LinkedSession or RPCSession.

from_py(py_object)[source]

Convert a Python object to its corresponding Gemstone representation.

This method creates an object in Gemstone corresponding to py_object of appopriate type. Apart from a few collections, this only supports basic types, such as unicode strings, various numbers and booleans.

Collections supported:

  • list - becomes an OrderedCollection

  • dict - becomes a Dictionary

  • set - becomes an IdentitySet

In the case of collections, the contents of the collections on the Gemstone side are created using session.from_py() on each element in the Python collections.

Parameters:

py_object – A Python object to convert

Returns:

A GemObject representing the converted object

Raises:

NotSupported – If the Python type cannot be converted

class reahl.ptongue.LinkedSession(username, password, stone_name='gs64stone', host_username=None, host_password='')[source]

Bases: GemstoneSession

A session that directly links to a GemStone database using the linked GCI API.

LinkedSession provides a client that runs inside the Python process (as opposed to RPCSession which connects to a remote server). Only one active LinkedSession can exist at a time per process.

Creating a LinkedSession implies logging in.

Parameters:

  • username – GemStone user account name used for authentication

  • password – GemStone password used for authentication

  • stone_name – Name of the GemStone repository to connect to, defaults to ‘gs64stone’

  • host_username – If specified, the OS username used for connecting to the server

  • host_password – Password for host_username, if required, defaults to empty string

abort()[source]

Abort the current transaction.

Any changes made since the last commit or abort will be discarded.

Raises:
begin()[source]

Begin a new transaction.

If there is an active transaction, it is aborted before starting a new one.

Raises:
commit()[source]

Commit the current transaction.

Write all changes made in the current transaction to the database.

Raises:

  • GemstoneApiError – If this session is not the current active session

  • GemstoneError – If the commit fails or an error occurs during the GemStone operation

execute(source, context=None, symbol_list=None)[source]

Execute GemStone Smalltalk code.

Parameters:

  • source – The Smalltalk code to execute, either as a Python string or a GemStone string object

  • context – The context object in which to execute the code, defaults to None (which uses the default nil context)

  • symbol_list – The symbol list to use for name resolution, defaults to None (which uses the default symbol list from the user’s profile)

Returns:

The result of executing the Smalltalk code

Raises:

  • GemstoneApiError – If this session is not the current active session, or if the source is not of the expected type

  • GemstoneError – If an error occurs during execution

property is_current_session

Check if this session is the current active linked session.

Only one linked session can be active at a time in a process.

Returns:

True if this is the current active session, False otherwise

property is_logged_in

Check if this session is currently logged in.

Returns:

True if the session is logged in, False otherwise

property is_remote

Determine whether this session is connected to a remote Gem.

For a LinkedSession, this should typically return False.

Returns:

True if connected to a remote Gem, False if using a linked Gem

Raises:
log_out()[source]

Log out from the GemStone session.

After log out, the session can no longer be used.

Raises:
new_symbol(py_string)[source]

Create a new GemStone Symbol object.

Parameters:

py_string – The Python string to be converted to a Symbol

Returns:

The new Symbol object

Raises:

  • GemstoneApiError – If this session is not the current active session

  • GemstoneError – If an error occurs, such as if the string is too long to be a Symbol

resolve_symbol(symbol, symbol_list=None)[source]

Resolve a symbol to its value in a symbol dictionary.

There is a shorthand for this method. These lines are equivalent:

session.SymbolName
session.resolve_symbol('SymbolName')
Parameters:

  • symbol – The name of the symbol to resolve, either as a Python string or a GemStone Symbol object

  • symbol_list – The symbol list to use for resolution, defaults to None (which uses the default symbol list from the user’s profile)

Returns:

The object that the symbol refers to

Raises:

  • GemstoneApiError – If this session is not the current active session, or if symbol is not of the expected type

  • GemstoneError – If the symbol cannot be resolved or another error occurs

class reahl.ptongue.RPCSession(username, password, stone_name='gs64stone', host_username=None, host_password=None, netldi_task='gemnetobject')[source]

Bases: GemstoneSession

A session that interacts with a remote Gemstone database via remote procedure call.

Creating an RPCSession implies logging in, and for a gem to be created for the session on the remote side.

Parameters:

  • username – GemStone username for repository authentication

  • password – GemStone password for repository authentication

  • stone_name – Name of the stone (repository) to connect to

  • host_username – Operating system username for host authentication

  • host_password – Operating system password for host authentication

  • netldi_task – Network service name

abort()[source]

Abort the current transaction.

Raises:

GemstoneError – If the abort operation fails

begin()[source]

Begin a new transaction.

Raises:

GemstoneError – If the begin operation fails

commit()[source]

Commit the current transaction.

Raises:

GemstoneError – If the commit operation fails

execute(source, context=None, symbol_list=None)[source]

Execute a GemStone Smalltalk expression.

Parameters:

  • source – String or GemObject containing Smalltalk code to execute

  • context – Optional context object for the execution

  • symbol_list – Optional symbol list for name resolution

Returns:

GemObject representing the result of execution

Raises:
property is_logged_in

Check if the session is currently logged in.

Returns:

True if the session is logged in, False otherwise

property is_remote

Check if the session is remote.

Returns:

True if the session is remote, False otherwise

Raises:

InvalidSession – If the session is invalid

log_out()[source]

Log out from the GemStone session.

Raises:

GemstoneError – If logout fails

new_symbol(py_string)[source]

Create a new GemStone symbol.

Parameters:

py_string – String to convert to a symbol

Returns:

GemObject representing the created symbol

Raises:

GemstoneError – If symbol creation fails

resolve_symbol(symbol, symbol_list=None)[source]

Resolve a symbol in the GemStone symbol list.

There is a shorthand for this method. These lines are equivalent:

session.SymbolName
session.resolve_symbol('SymbolName')
Parameters:

  • symbol – String or GemObject symbol to resolve

  • symbol_list – Optional symbol list for resolution

Returns:

GemObject representing the resolved symbol

Raises:
exception reahl.ptongue.GemstoneError(sess, c_error)[source]

Bases: Exception

Represents an exception that happened in a Gem.

This class encapsulates errors that occurred within the Gemstone virtual machine, providing a Python-friendly interface to access information about the exception.

This class is not a GemObject like other Gem objects because it needs to be a Python Exception to work properly with Python’s exception handling mechanisms.

Parameters:

  • sess – The GemstoneSession where the error occurred.

  • c_error – A C structure containing the error details.

property args

Get the arguments of the exception.

These are the arguments that were provided when the error was signaled, which provide additional context about the error condition.

Returns:

A list of GemObjects representing the exception arguments, or None if no arguments were provided.

clear_stack()[source]

Clear the stack of the process where the exception occurred.

This terminates the execution context of the GsProcess where the error occurred, resetting it to a clean state.

Returns:

The result of clearing the stack.

property context

Get the context where the exception occurred.

The context is typically a GsProcess object representing the Smalltalk execution state at the time of the error. This can be used for debugging and to manipulate the execution state.

Returns:

A GemObject representing the GsProcess context, or None if no context was provided.

continue_with(continue_with_error=None, replace_top_of_stack=None)[source]

Continue execution after the exception.

This method allows for resuming execution at the point where the exception occurred, similar to how Smalltalk exceptions can be resumed.

Parameters:

  • continue_with_error – Another GemstoneError to continue with. If provided, this error will be signaled instead, and replace_top_of_stack must be None.

  • replace_top_of_stack – A GemObject to replace the top of the stack. This is used if continue_with_error is None.

Returns:

The result of continuing execution as a GemObject.

property exception_obj

Get the actual exception object from Gemstone.

This is an instance of AbstractException or one of its subclasses that was signaled in the Gemstone environment. This may be nil if the error was not signaled from Smalltalk execution.

Returns:

A GemObject representing the AbstractException, or None if no exception object was provided.

property is_fatal

Check if this is a fatal error.

Fatal errors typically cannot be recovered from and may indicate serious problems with the Gemstone server that require administrative intervention.

Returns:

True if the error is fatal, False otherwise.

property message

Get the error message.

This contains the formatted error text, including any arguments that were provided.

Returns:

A UTF-8 decoded string containing the error message.

property number

Get the numeric error code for this exception.

Gemstone assigns numeric codes to common errors. These can be used to identify specific error conditions programmatically.

Returns:

An integer representing the Gemstone error number.

property reason

Get the reason for the exception.

This field may contain additional context about why the exception occurred.

Returns:

A UTF-8 decoded string containing the reason for the exception.

exception reahl.ptongue.InvalidSession[source]

Bases: Exception

Indicates a problem with the current Session.

exception reahl.ptongue.NotSupported[source]

Bases: Exception

Thrown when an attempt is made to do something that is not supported. For example, if you try to transfer a type of Python object to Gemstone which cannot be transferred.

exception reahl.ptongue.GemstoneApiError[source]

Bases: Exception

Thrown when problems are detected while communicating via the underlying C API.

exception reahl.ptongue.GemstoneWarning[source]

Bases: Warning

Represents a warning condition related to this API.

Submodules