barentsz 1.2.1

For discovering modules, classes, functions and attributes.

Barentsz

⛵ Explore and discover modules, classes, functions, attributes.

pip install barentsz

❄ Overview

• Discover all packages in a path;
• Discover all modules in a path;
• Discover all/some classes in a path or module;
• Discover all/some functions in a path, module or class;
• Discover all/some attributes in a path or module.

List of all features

>>> import barentsz
>>> for feature in (f for f in dir(barentsz) if not f.startswith('_')):
...     print(feature)
discover
discover_attributes
discover_classes
discover_functions
discover_module_names
discover_modules
discover_packages
discover_paths
here

❄ Features in detail

The sections below contain all features that are offered by this lib. For the API details, please see the Help documentation subsections.

Discover

Import

>>> from barentsz import discover

Usage Example

>>> discover('./test_resources/examples_for_readme')
[<class 'examples_for_readme.module_a.ClassA'>, <class 'examples_for_readme.module_b.ClassB'>]

Help documentation

>>> help(discover)
Help on function discover in module barentsz._discover:
<BLANKLINE>
discover(source: Any = None, *, what: Any = typing.List[type], **kwargs: dict) -> list
    Convenience function for discovering types in some source. If not source
    is given, the directory is used in which the calling module is located.
<BLANKLINE>
    Args:
        source: the source in which is searched or the directory of the
        caller if None.
        what: the type that is to be discovered.
        **kwargs: any keyword argument that is passed on.
<BLANKLINE>
    Returns: a list of discoveries.
<BLANKLINE>

Discover Classes

Import

>>> from barentsz import discover_classes

Usage Example

>>> discover_classes('./test_resources/examples_for_readme')
[<class 'examples_for_readme.module_a.ClassA'>, <class 'examples_for_readme.module_b.ClassB'>]

Help documentation

>>> help(discover_classes)
Help on function discover_classes in module barentsz._discover:
<BLANKLINE>
discover_classes(source: Union[pathlib.Path, str, module, Iterable[module]], signature: type = typing.Any, include_privates: bool = False, in_private_modules: bool = False, raise_on_fail: bool = False, exclude: Union[type, Callable[[type], bool], Iterable[Union[type, Callable[[type], bool]]]] = None) -> List[type]
    Discover any classes within the given source and according to the given
    constraints.
<BLANKLINE>
    Args:
        source: the source in which is searched for any classes.
        signature: only classes that inherit from signature are returned.
        include_privates: if True, private classes are included as well.
        in_private_modules: if True, private modules are explored as well.
        raise_on_fail: if True, raises an ImportError upon the first import
        failure.
        exclude: one or more types or predicates that are to be excluded
        from the result.
<BLANKLINE>
    Returns: a list of all discovered classes (types).
<BLANKLINE>

Discover Functions

Import

>>> from barentsz import discover_functions

Usage Example

>>> functions = discover_functions('./test_resources/examples_for_readme')
>>> [f.__name__ for f in functions]
['function_a', 'function_b']

Help documentation

>>> help(discover_functions)
Help on function discover_functions in module barentsz._discover:
<BLANKLINE>
discover_functions(source: Union[pathlib.Path, str, module, Iterable[module], type], signature: Type[Callable] = typing.Callable, include_privates: bool = False, in_private_modules: bool = False, raise_on_fail: bool = False) -> List[type]
    Discover any functions within the given source and according to the given
    constraints.
<BLANKLINE>
    Args:
        source: the source in which is searched for any functions.
        signature: only functions that have this signature (parameters and
        return type) are included.
        include_privates: if True, private functions are included as well.
        in_private_modules: if True, private modules are explored as well.
        raise_on_fail: if True, raises an ImportError upon the first import
        failure.
<BLANKLINE>
    Returns: a list of all discovered functions.
<BLANKLINE>

Discover Attributes

Import

>>> from barentsz import discover_attributes

Usage Example

>>> attributes = discover_attributes('./test_resources/examples_for_readme')
>>> [a.name for a in attributes]
['attr_a', 'attr_b']

Help documentation

>>> help(discover_attributes)
Help on function discover_attributes in module barentsz._discover:
<BLANKLINE>
discover_attributes(source: Union[pathlib.Path, str, module, Iterable[module]], signature: type = typing.Any, include_privates: bool = False, in_private_modules: bool = False, raise_on_fail: bool = False) -> List[barentsz._attribute.Attribute]
    Discover any attributes within the given source and according to the given
    constraints.
<BLANKLINE>
    Args:
        source: the source in which is searched for any attributes.
        signature: only attributes that are subtypes of this signature are
        included.
        include_privates: if True, private attributes are included as well.
        in_private_modules: if True, private modules are explored as well.
        raise_on_fail: if True, raises an ImportError upon the first import
        failure.
<BLANKLINE>
    Returns: a list of all discovered attributes.
<BLANKLINE>

Discover Modules

Import

>>> from barentsz import discover_modules

Usage Example

>>> modules = discover_modules('./test_resources/examples_for_readme')
>>> [m.__name__ for m in modules]
['examples_for_readme.module_a', 'examples_for_readme.module_b']

Help documentation

>>> help(discover_modules)
Help on function discover_modules in module barentsz._discover:
<BLANKLINE>
discover_modules(directory: Union[pathlib.Path, str], include_privates: bool = False, raise_on_fail: bool = False) -> List[module]
    Return a list of modules within the given directory. The directory must be
    a package and only modules are returned that are in packages.
    Args:
        directory: the directory in which is searched for modules.
        include_privates: if True, privates (unders and dunders) are also
        included.
        raise_on_fail: if True, an ImportError is raised upon failing to
        import any module.
<BLANKLINE>
    Returns: a list of module objects.
<BLANKLINE>

Discover Packages

Import

>>> from barentsz import discover_packages

Usage Example

>>> discover_packages('./test_resources/examples_for_readme')
['examples_for_readme']

Help documentation

>>> help(discover_packages)
Help on function discover_packages in module barentsz._discover:
<BLANKLINE>
discover_packages(directory: Union[pathlib.Path, str]) -> List[str]
    Return a list of packages within the given directory. The directory must be
    a package.
    Args:
        directory: the directory in which is searched for packages.
<BLANKLINE>
    Returns: a list of packages.
<BLANKLINE>

Current Directory (here)

Import

>>> from barentsz import here

Usage Example

>>> str(here())
'.'

Help documentation

>>> help(here)
Help on function here in module barentsz._here:
<BLANKLINE>
here(frames_back: int = 0) -> pathlib.Path
    Get the current directory from which this function is called.
    Args:
        frames_back: the number of extra frames to look back.
<BLANKLINE>
    Returns: the directory as a Path instance.
<BLANKLINE>

Discover Paths

Import

>>> from barentsz import discover_paths

Usage Example

>>> paths = discover_paths('./test_resources/examples_for_readme', '**/*.py')
>>> [str(p.as_posix()) for p in paths]
['test_resources/examples_for_readme/__init__.py', 'test_resources/examples_for_readme/module_a.py', 'test_resources/examples_for_readme/module_b.py']

Help documentation

>>> help(discover_paths)
Help on function discover_paths in module barentsz._discover:
<BLANKLINE>
discover_paths(directory: Union[pathlib.Path, str], pattern: str) -> List[pathlib.Path]
    Return a list of Paths within the given directory that match the given
    pattern.
<BLANKLINE>
    Args:
        directory: the directory in which is searched for paths.
        pattern: a pattern (example: '**/*.py').
<BLANKLINE>
    Returns: a list of Path objects.
<BLANKLINE>

❄ (Not So) Frequently Asked Questions

1. When is Barentsz particularly useful?

   When e.g. adding a class to some package and you want it to be picked up in your application, without having to add an import or registration somewhere.

2. Does Barentsz require my classes to be compromised (e.g. with inheritance or a decorator or something)?

   No, never.

3. What must I do for Barentsz to discover my class (or function, attribute, etc.)?

   Nothing special. Just make sure that the path that is explored is a Python package.

4. Why do the "Help documentation" sections contain this "<BLANKLINE>"?

   That's because this documentation is under doctest. It helps to ensure that the documentation is always up to date.

5. What's with the funny name?

   Well... since this library is all about exploring and discovering and because I really enjoyed the cold north, I thought it to be a fitting name.

6. What is the answer to the Ultimate Question of Life, the Universe, and Everything?

   Haven't got a clue, what are you asking me for anyway? I suggest you build an AI to deduce the answer (using barentsz of course).

❄ Changelist

1.2.1 [2020-09-26]

• Fix for a bug when discovering using a relative path.

1.2.0 [2020-09-20]

• Changed exclude parameter to also allow predicates.

1.1.0 [2020-08-05]

• Added the here function that returns the directory of the caller of that function.
• Added the discovery function that can conveniently find types using the current dir and a given class.
• Added exclude to discover_classes to allow for excluding one or more types from discovery.
• Fix for double discovered classes.

1.0.0 [2020-07-28]

• First release. 🎉