Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ramonhagenaars/barentsz
⛵ Explore and discover modules, classes, functions, attributes
https://github.com/ramonhagenaars/barentsz
Last synced: 6 days ago
JSON representation
⛵ Explore and discover modules, classes, functions, attributes
- Host: GitHub
- URL: https://github.com/ramonhagenaars/barentsz
- Owner: ramonhagenaars
- License: mit
- Created: 2020-02-29T16:43:56.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2020-09-26T12:15:33.000Z (about 4 years ago)
- Last Synced: 2024-09-24T09:18:17.233Z (about 2 months ago)
- Language: Python
- Homepage:
- Size: 158 KB
- Stars: 3
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://img.shields.io/pypi/pyversions/barentsz.svg)
[](https://badge.fury.io/py/barentsz)
[](https://codecov.io/gh/ramonhagenaars/barentsz)
[](https://scrutinizer-ci.com/g/ramonhagenaars/barentsz/?branch=master)
# 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
```python
>>> 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
```python
>>> from barentsz import discover
```
##### Usage Example
```python
>>> discover('./test_resources/examples_for_readme')
[, ]
```
##### Help documentation
```python
>>> help(discover)
Help on function discover in module barentsz._discover:
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.
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.
Returns: a list of discoveries.
```
### Discover Classes
##### Import
```python
>>> from barentsz import discover_classes
```
##### Usage Example
```python
>>> discover_classes('./test_resources/examples_for_readme')
[, ]
```
##### Help documentation
```python
>>> help(discover_classes)
Help on function discover_classes in module barentsz._discover:
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.
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.
Returns: a list of all discovered classes (types).
```
### Discover Functions
##### Import
```python
>>> from barentsz import discover_functions
```
##### Usage Example
```python
>>> functions = discover_functions('./test_resources/examples_for_readme')
>>> [f.__name__ for f in functions]
['function_a', 'function_b']
```
##### Help documentation
```python
>>> help(discover_functions)
Help on function discover_functions in module barentsz._discover:
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.
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.
Returns: a list of all discovered functions.
```
### Discover Attributes
##### Import
```python
>>> from barentsz import discover_attributes
```
##### Usage Example
```python
>>> attributes = discover_attributes('./test_resources/examples_for_readme')
>>> [a.name for a in attributes]
['attr_a', 'attr_b']
```
##### Help documentation
```python
>>> help(discover_attributes)
Help on function discover_attributes in module barentsz._discover:
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.
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.
Returns: a list of all discovered attributes.
```
### Discover Modules
##### Import
```python
>>> from barentsz import discover_modules
```
##### Usage Example
```python
>>> 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
```python
>>> help(discover_modules)
Help on function discover_modules in module barentsz._discover:
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.
Returns: a list of module objects.
```
### Discover Packages
##### Import
```python
>>> from barentsz import discover_packages
```
##### Usage Example
```python
>>> discover_packages('./test_resources/examples_for_readme')
['examples_for_readme']
```
##### Help documentation
```python
>>> help(discover_packages)
Help on function discover_packages in module barentsz._discover:
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.
Returns: a list of packages.
```
### Current Directory (here)
##### Import
```python
>>> from barentsz import here
```
##### Usage Example
```python
>>> str(here())
'.'
```
##### Help documentation
```python
>>> help(here)
Help on function here in module barentsz._here:
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.
Returns: the directory as a Path instance.
```
### Discover Paths
##### Import
```python
>>> from barentsz import discover_paths
```
##### Usage Example
```python
>>> 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
```python
>>> help(discover_paths)
Help on function discover_paths in module barentsz._discover:
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.
Args:
directory: the directory in which is searched for paths.
pattern: a pattern (example: '**/*.py').
Returns: a list of Path objects.
```
## ❄ (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 "\"?
_That's because this documentation is under [doctest](https://docs.python.org/3/library/doctest.html).
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. 🎉