For discovering modules, classes, functions and attributes.
Project description
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.
❄ Features in detail
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) -> 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.
<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>
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/module_a.py', 'test_resources/examples_for_readme/module_b.py', 'test_resources/examples_for_readme/__init__.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
-
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.
-
Does Barentsz require my classes to be compromised (e.g. with inheritance or a decorator or something)?
No, never.
-
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.
-
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.
-
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.
❄ Changelist
1.0.0 [2020-07-28]
- First release. 🎉
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.