core-extensions 2.0.0

This project contains common elements for different projects. Unlike `core-mixins`, this project requires external dependencies...

core-extensions

This project contains common elements for different projects. Unlike core-mixins, this project requires external dependencies…

---

Installation

Install from PyPI using pip:

pip install core-extensions
uv pip install core-extensions  # Or using UV...

Features

This library provides a collection of utilities and extensions for projects:

Retry Decorator Advanced retry mechanism based on the tenacity library with exponential backoff, custom exception handling, and detailed logging.

from core_extensions.decorators.retry import SimpleRetry

retry_handler = SimpleRetry(max_attempts=3, base_delay=1.0)

@retry_handler.create_decorator((ConnectionError, TimeoutError))
def fetch_data():
    return api.get_data()

Aliased CLI Group Click extension that allows defining command aliases for better user experience and backward compatibility in CLI applications.

from core_extensions.cli import AliasedGroup

cli = AliasedGroup()

@cli.command("deploy", aliases=["release", "publish"])
def deploy_command():
    """Deploy the application"""
    print("Deploying...")

@cli.group("infra", aliases=["i", "infrastructure"])
def infra_group():
    """Infrastructure commands"""

Aliases are shown automatically in --help output:

Commands:
  deploy  Deploy the application  (aliases: release, publish)
  infra   Infrastructure commands  (aliases: i, infrastructure)

Registering the same alias on two different commands raises ValueError immediately at decoration time, preventing silent routing bugs.

By default a subgroup is a plain click.Group, so its commands do not support aliases. Pass cls=AliasedGroup to enable full alias support at every level:

@cli.group("db", aliases=["database"], cls=AliasedGroup)
def db_group():
    """Database commands"""

@db_group.command("migrate", aliases=["m"])
def db_migrate():
    """Run pending migrations"""

Quick Start

Installation

Install the package:

pip install core-extensions
uv pip install core-extensions  # Or using UV...
pip install -e ".[dev]"    # For development...

Setting Up Environment

1. Install required libraries:

pip install --upgrade pip
pip install virtualenv

2. Create Python virtual environment:

virtualenv --python=python3.12 .venv

3. Activate the virtual environment:

source .venv/bin/activate

Install packages

pip install .
pip install -e ".[dev]"

Testing

The project ships two complementary test suites:

• Unit tests — isolated, mocked, deterministic; one file per module.

• Integration tests — end-to-end scenarios using Click’s CliRunner and live tenacity retry machinery; no mocking of internal collaborators.

tests/
├── unit/
│   ├── cli/tests_aliased_group.py
│   └── decorators/tests_retry.py
└── integration/
    ├── test_cli_integration.py
    └── test_retry_integration.py

Run unit tests only:

pytest tests/unit/

Run integration tests only:

pytest tests/integration/

Run both suites with branch coverage:

pytest tests/ --cov=core_extensions --cov-branch --cov-report=term-missing

Or use the helper script:

python manager.py run-tests
python manager.py run-coverage

Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Write tests for new functionality

4. Ensure all tests pass: pytest -n auto

5. Run linting: pylint core_extensions

6. Run security checks: bandit -r core_extensions

7. Submit a pull request

License

This project is licensed under the MIT License. See the LICENSE file for details.

Links

• Documentation: https://core-extensions.readthedocs.io/en/latest/

• Repository: https://gitlab.com/bytecode-solutions/core/core-extensions

• Issues: https://gitlab.com/bytecode-solutions/core/core-extensions/-/issues

• Changelog: https://gitlab.com/bytecode-solutions/core/core-extensions/-/blob/master/CHANGELOG.md

• PyPI: https://pypi.org/project/core-extensions/

Support

For questions or support, please open an issue on GitLab or contact the maintainers.

Authors

• Alejandro Cora González - Initial work - [e-mail]