.. module:: firebird.base.types
   :synopsis: Common data types

#########################
types - Common data types
#########################

Overview
========

This module provides collection classes that are often used by other library modules or
applications.

Exceptions
==========

Error
-----
.. autoexception:: Error
   :show-inheritance:
   :no-inherited-members:

Singletons
==========

Singleton is a pattern that restricts the instantiation of a class to one "single" instance.
This is useful when exactly one object is needed to coordinate actions across the system.

Common uses:

- The abstract factory, factory method, builder, and prototype patterns can use singletons
  in their implementation.
- Facade objects are often singletons because only one facade object is required.
- State objects are often singletons.
- Singletons are often preferred to global variables because:

  - They do not pollute the global namespace with unnecessary variables.
  - They permit lazy allocation and initialization.

To create your own singletons, use `Singleton` as the base class.

.. admonition:: example

      >>> class MySingleton(Singleton):
      ...     "Description"
      ...     ...
      ...
      >>> obj1 = MySingleton()
      >>> obj1 = MySingleton()
      >>> obj1 is obj2
      True

Singleton
---------
.. autoclass:: Singleton

Sentinels
=========

The Sentinel Object pattern is a standard Pythonic approach that’s used both in the
Standard Library and beyond. The pattern most often uses Python’s built-in `None` object,
but in situations where None might be a useful value, a unique sentinel `object()` can be
used instead to indicate missing or unspecified data, or other specific condition.

However, the plain `object()` sentinel has not very useful `str` and `repr` values.
The `Sentinel` class provides named sentinels, with meaningful `str` and `repr`.

Sentinel
--------
.. autoclass:: Sentinel

Predefined sentinels
--------------------

.. autodata:: DEFAULT
.. autodata:: INFINITY
.. autodata:: UNLIMITED
.. autodata:: UNKNOWN
.. autodata:: NOT_FOUND
.. autodata:: UNDEFINED
.. autodata:: ANY
.. autodata:: ALL
.. autodata:: SUSPEND
.. autodata:: RESUME
.. autodata:: STOP

Distinct objects
================

Some complex data structures or data processing algorithms require unique object
identification (ie object identity). In Python, an object identity is defined internally
as a unique instance identity that is not suitable for complex objects whose identity is
derived from content.

The `Distinct` abstract base class is intended as a unified solution to these needs.

.. seealso:: module `firebird.base.collections`


Distinct
--------
.. autoclass:: Distinct

CachedDistinct
--------------
.. autoclass:: CachedDistinct

Enums
=====

ByteOrder
---------
.. autoclass:: ByteOrder

ZMQTransport
------------
.. autoclass:: ZMQTransport

ZMQDomain
---------
.. autoclass:: ZMQDomain

Custom string types
===================

Some string values have unified structure and carry specific information (like network
address or database connection string). Typical repeating operation with these values
are validation and parsing. It makes sense to put these operations under one roof.
One such approach uses custom descendants of builtin `str` type.

.. caution::

   Custom string types have an inherent weakness. They support all inherited string methods,
   but any method that returns string value return a base `str` type, not the decendant class
   type. That same apply when you assign strings to variables that should be of custom
   string type.

   .. tip::

      Module `~firebird.base.strconv` could help you to safely translate strings stored
      externally to typed strings.

ZeroMQ address
--------------
.. autoclass:: ZMQAddress

MIME
----
.. autoclass:: MIME

PyExpr
------
.. autoclass:: PyExpr

PyCode
------
.. autoclass:: PyCode

PyCallable
----------
.. autoclass:: PyCallable

Meta classes
============

SingletonMeta
-------------
.. autoclass:: SingletonMeta

SentinelMeta
------------
.. autoclass:: SentinelMeta

CachedDistinctMeta
------------------
.. autoclass:: CachedDistinctMeta

Conjunctive
-----------
.. autofunction:: Conjunctive
