aglyph — Dependency Injection for Python

Release:2.1.1

This module defines a custom error type and several utility functions used by Aglyph.

Aglyph is fully logged using the standard logging module, but by default uses a no-op logging handler to suppress log messages. If you want to enable Aglyph logging, define a logger for the “aglyph” log channel in your application’s logging configuration (see logging.config for more information).

exception aglyph.AglyphDeprecationWarning(name, replacement=None)[source]

Bases: DeprecationWarning

Issued when deprecated Aglyph functions, classes, or methods are used.

Parameters:
  • name (str) – the name of the deprecated function, class, or method
  • replacement (str) – the name of the replacement function, class, or method (if applicable)
exception aglyph.AglyphError[source]

Bases: Exception

Raised when Aglyph operations fail with a condition that is not sufficiently described by a built-in exception.

aglyph.has_importable_dotted_name(obj)[source]

Tell whether or not obj can be represented as an importable dotted-name string.

Parameters:obj – any object
Returns:True if obj is an importable class or unbound function, else False

Deprecated since version 2.0.0: This function has no replacement and will be removed in release 3.0.0.

aglyph.format_dotted_name(obj)[source]

Return the importable dotted-name string for obj.

Parameters:

obj – an importable class, function, or module

Returns:

a dotted name representing obj

Return type:

str

Raises:
  • TypeError – if obj is not a class, unbound function, or module
  • ValueError – if the dotted name for obj is not importable

The dotted name returned by this function is a “dotted_name.NAME” or “dotted_name” string for obj that represents a valid absolute import statement according to the following productions:

absolute_import_stmt ::=  "from" dotted_name "import" NAME
                          | "import" dotted_name
dotted_name          ::=  NAME ('.' NAME)*

Note

This function is the inverse of resolve_dotted_name().

Warning

This function will attempt to use the __qualname__ attribute, which is only available in Python 3.3+. When __qualname__ is not available, __name__ is used instead.

As a result, using this function to format the dotted name of a nested class, class method, or static method will fail if not running on Python 3.3+.

aglyph.identify_by_spec(spec)[source]

Generate a unique identifier for spec.

Parameters:spec – an importable class, function, or module; or a str
Returns:spec unchanged (if it is a str), else spec‘s importable dotted name
Return type:str

If spec is a string, it is assumed to already represent a unique identifier and is returned unchanged. Otherwise, spec is assumed to be an importable class, function, or module, and its dotted name is returned (see format_dotted_name()).

Deprecated since version 2.0.0: This function has no replacement and will be removed in release 3.0.0.

aglyph.resolve_dotted_name(dotted_name)[source]

Return the class, function, or module identified by dotted_name.

Parameters:dotted_name (str) – a string representing an importable class, function, or module
Returns:a class, function, or module

dotted_name must be a “dotted_name.NAME” or “dotted_name” string that represents a valid absolute import statement according to the following productions:

absolute_import_stmt ::=  "from" dotted_name "import" NAME
                          | "import" dotted_name
dotted_name          ::=  NAME ('.' NAME)*

Note

This function is the inverse of format_dotted_name().