Metadata-Version: 2.4
Name: twat-labs
Version: 2.7.8
Project-URL: Documentation, https://github.com/twardoch/twat-labs#readme
Project-URL: Issues, https://github.com/twardoch/twat-labs/issues
Project-URL: Source, https://github.com/twardoch/twat-labs
Author-email: Adam Twardoch <adam+github@twardoch.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.10
Requires-Dist: twat>=1.8.1
Provides-Extra: all
Requires-Dist: twat>=1.8.1; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.15.0; extra == 'dev'
Requires-Dist: pre-commit>=4.1.0; extra == 'dev'
Requires-Dist: ruff>=0.9.6; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.27.0; extra == 'docs'
Provides-Extra: test
Requires-Dist: pytest-benchmark[histogram]>=5.1.0; extra == 'test'
Requires-Dist: pytest-cov>=6.0.0; extra == 'test'
Requires-Dist: pytest-xdist>=3.6.1; extra == 'test'
Requires-Dist: pytest>=8.3.4; extra == 'test'
Description-Content-Type: text/markdown

# twat-labs

**`twat-labs` is a plugin for the `twat` ecosystem, a collection of tools and libraries available on PyPI. This specific package, `twat-labs`, is designed to host experimental features, new extensions, or specialized utilities that are under development or evaluation before potential integration into the core `twat` offerings or other specialized `twat` packages.**

It's part of the [twat](https://pypi.org/project/twat/) collection of Python packages.

## What is `twat-labs`?

`twat-labs` serves as a proving ground for innovative or niche functionalities related to the broader `twat` system. While the core `twat` project provides stable and well-tested tools, `twat-labs` offers a space for developers and users to explore cutting-edge capabilities.

Currently, in its initial phase, `twat-labs` primarily establishes the plugin structure and includes basic versioning. As it evolves, it will house more concrete experimental features.

## Who is it for?

*   **Users of the `twat` ecosystem:** If you use `twat` tools and are interested in trying out upcoming features or need specialized functionalities that are not yet in the main releases, `twat-labs` is for you.
*   **Python Developers:** If you are contributing to the `twat` ecosystem or developing tools that integrate with it, `twat-labs` provides examples of plugin structure and a place to potentially contribute experimental modules.

## Why is it useful?

*   **Access to Experimental Features:** Get early access to new tools and functionalities being developed for the `twat` ecosystem.
*   **Extensibility:** Provides a clear mechanism for extending the `twat` system with new capabilities.
*   **Feedback Loop:** Allows developers to gather feedback on new features before they are finalized.

## Installation

You can install `twat-labs` using pip:

```bash
pip install twat-labs
```

This will install the latest stable version from PyPI.

## How to Use

### Programmatic Usage

As a Python library, `twat-labs` can be imported into your Python projects. Currently, its primary exposed feature is its version information, which is a common practice for plugins to allow host systems to identify them:

```python
import twat_labs

print(f"twat-labs version: {twat_labs.__version__}")

# Future functionalities will be accessible here
# For example:
# if hasattr(twat_labs, 'experimental_feature_x'):
#     twat_labs.experimental_feature_x()
```

### Command-Line Interface (CLI) Usage

It is anticipated that `twat-labs`, as a plugin for the `twat` ecosystem, may extend a `twat` CLI if one exists. For example, if `twat` is a command-line tool, installing `twat-labs` might automatically make new subcommands or options available.

Example (hypothetical, depends on the main `twat` tool):

```bash
# Assuming 'twat' is the main CLI tool
twat labs-feature --option
```

The exact CLI usage will depend on how the main `twat` application discovers and integrates its plugins. Please refer to the documentation of the core `twat` tool for details on how it manages plugins.

## Technical Deep-Dive

This section provides a more detailed look into the internal workings of `twat-labs`, its development practices, and how to contribute.

### Code Overview

*   **Plugin Registration:** `twat-labs` is registered as a plugin within the `twat` ecosystem using Python's entry points mechanism. This is defined in the `pyproject.toml` file under the `[project.entry-points."twat.plugins"]` table:
    ```toml
    [project.entry-points."twat.plugins"]
    labs = "twat_labs"
    ```
    This allows the main `twat` application to discover and load `twat-labs` if it's installed in the same Python environment.

*   **Current Functionality:** As of now, the primary functionality within the `src/twat_labs/__init__.py` module is to expose its version:
    ```python
    from twat_labs.__version__ import version as __version__

    __all__ = ["__version__"]
    ```
    The actual version string is dynamically generated at build time by `hatch-vcs` based on Git tags and stored in `src/twat_labs/__version__.py`.

*   **Project Structure:**
    *   `src/twat_labs/`: Contains the main source code for the plugin.
    *   `tests/`: Contains test suites for the project, written using `pytest`.
    *   `pyproject.toml`: The heart of the project's build system and metadata, compliant with PEP 621.
    *   `.github/workflows/`: Defines CI/CD pipelines using GitHub Actions for automated testing and releases.

### Build and Dependency Management

`twat-labs` uses modern Python packaging standards and tools:

*   **`pyproject.toml` (PEP 621):** This file defines all project metadata, dependencies, and tool configurations.
*   **`hatch`:** The project uses [Hatch](https://hatch.pypa.io/) as its primary tool for development workflow management. Key `hatch` commands include:
    *   `hatch shell`: Activates the project's isolated development environment with all dependencies installed.
    *   `hatch run test`: Executes the test suite using `pytest`.
    *   `hatch run test-cov`: Runs tests with coverage reporting.
    *   `hatch run lint`: Runs linters (`ruff`) and type checkers (`mypy`).
    *   `hatch run format`: Formats code using `ruff format`.
    Refer to the `[tool.hatch.envs.default.scripts]` and `[tool.hatch.envs.lint.scripts]` sections in `pyproject.toml` for a full list of available scripts.

*   **Versioning with `hatch-vcs`:** The project's version is dynamically determined from Git tags (e.g., `v1.0.0`). `hatch-vcs` generates the `src/twat_labs/__version__.py` file during the build process. This means manual updates to the version in source files are not required; versioning is managed by creating new Git tags.

### Coding and Contribution Rules

To maintain code quality and consistency, `twat-labs` adheres to the following practices:

*   **Linting and Formatting with `ruff`:**
    *   [Ruff](https://beta.ruff.rs/docs/) is used for extremely fast Python linting and formatting.
    *   Configuration is stored in the `[tool.ruff]` section of `pyproject.toml`.
    *   Key rules include adherence to PEP 8, various flake8 plugins, and import sorting (`isort` conventions).
    *   Run `hatch run lint:style` or `hatch run lint:fmt` to check and format code.

*   **Static Type Checking with `mypy`:**
    *   The project enforces static type checking using [Mypy](http://mypy-lang.org/).
    *   Configuration is in the `[tool.mypy]` section of `pyproject.toml`.
    *   Strict rules are enabled (e.g., `disallow_untyped_defs`, `no_implicit_optional`).
    *   Run `hatch run lint:typing` or `hatch run type-check` to perform type checks.
    *   All new code contributions must include type hints.

*   **Testing with `pytest`:**
    *   Tests are located in the `tests/` directory and are written using the [pytest](https://docs.pytest.org/) framework.
    *   Comprehensive tests are expected for all new features and bug fixes.
    *   Run tests with `hatch run test`. Coverage reports can be generated with `hatch run test-cov`.
    *   The `pyproject.toml` file contains configurations for `pytest` under `[tool.pytest.ini_options]`.

*   **Pre-commit Hooks:**
    *   The project uses pre-commit hooks configured in `.pre-commit-config.yaml`. These hooks typically run linters and formatters automatically before each commit, ensuring that contributions adhere to the project's coding standards.

*   **Changelog (`CHANGELOG.md`):**
    *   All notable changes, including new features, bug fixes, and improvements, must be documented in `CHANGELOG.md`.
    *   The changelog follows the principles of [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

*   **CI/CD with GitHub Actions:**
    *   The workflows defined in `.github/workflows/` (e.g., `push.yml`, `release.yml`) automate testing across different Python versions and operating systems upon pushes and pull requests.
    *   Successful merges to the main branch that include new version tags can trigger automated releases to PyPI.

*   **Contribution Process:**
    1.  **Fork the repository** on GitHub.
    2.  **Create a new branch** for your feature or bug fix: `git checkout -b feature/your-feature-name` or `git checkout -b fix/issue-number`.
    3.  **Make your changes,** adhering to the coding standards (linting, typing, testing).
    4.  **Add tests** for your changes.
    5.  **Update `CHANGELOG.md`** with a description of your changes.
    6.  **Commit your changes** with a clear and descriptive commit message.
    7.  **Push your branch** to your fork: `git push origin feature/your-feature-name`.
    8.  **Open a Pull Request** to the main `twat-labs` repository.
    9.  Ensure all CI checks pass.

By following these guidelines, contributors can help ensure that `twat-labs` remains a high-quality, robust, and maintainable project.
