Metadata-Version: 2.1
Name: wexample-remote
Version: 1.1.0
Author-Email: weeger <contact@wexample.com>
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Requires-Dist: wexample-api
Requires-Dist: wexample-helpers>=20.1.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Description-Content-Type: text/markdown

# remote

Version: 1.1.0

## A remote

```python
from wexample_remote import AbstractRemote, RemoteStatus

class RenderServerRemote(AbstractRemote):
    def get_key(self) -> str:
        return "render_server"

    def check_status(self) -> RemoteStatus:
        return RemoteStatus.up() if renderer.ping() else RemoteStatus.down("No answer.")
```

`AbstractRemote` carries no field, so a class already built on another base — a gateway, a connector — takes it as a mixin. `get_label()` defaults to the key. A check may raise instead of returning `down()`: the registry reports the exception message.

## The registry

```python
from wexample_remote import RemoteRegistry

registry = RemoteRegistry([render_server, billing])

registry.check("billing")      # RemoteStatus, with its latency in milliseconds
registry.check_all()           # dict of RemoteStatus, by key
registry.check("billing").to_dict()
```

Two remotes sharing a key are refused; an unknown key raises `RemoteNotFoundException`.

## A wexample-api gateway

```python
from wexample_remote import GatewayRemote

remote = GatewayRemote(gateway=billing_gateway, key="billing", label="Billing API", ping_path="health")
```

It reads unconfigured while the gateway has no base URL, and otherwise requests the ping path: any status below 400 is up. A subclass adds its own missing settings by overriding `get_missing_settings()`.

## Table of Contents

- [A remote](#a-remote)
- [The registry](#the-registry)
- [A wexample-api gateway](#a-wexample-api-gateway)
- [Installation](#installation)
- [Tests](#tests)
- [Architecture](#architecture)
- [Integration in the Suite](#integration-in-the-suite)
- [Dependencies](#dependencies)
- [Versioning & Compatibility Policy](#versioning--compatibility-policy)
- [License](#license)
- [About us](#about-us)
- [Known Limitations & Roadmap](#known-limitations--roadmap)
- [Status & Compatibility](#status--compatibility)
- [Useful Links](#useful-links)
- [Migration Notes](#migration-notes)

## Installation

```bash
pip install wexample-remote
```

Requires Python >=3.10.

## Tests

This project uses `pytest` for testing and `pytest-cov` for code coverage analysis.

### Installation

First, install the required testing dependencies:
```bash
.venv/bin/python -m pip install pytest pytest-cov
```

### Basic Usage

Run all tests with coverage:
```bash
.venv/bin/python -m pytest --cov --cov-report=html
```

### Common Commands
```bash
# Run tests with coverage for a specific module
.venv/bin/python -m pytest --cov=your_module

# Show which lines are not covered
.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing

# Generate an HTML coverage report
.venv/bin/python -m pytest --cov=your_module --cov-report=html

# Combine terminal and HTML reports
.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing --cov-report=html

# Run specific test file with coverage
.venv/bin/python -m pytest tests/test_file.py --cov=your_module --cov-report=term-missing
```

### Viewing HTML Reports

After generating an HTML report, open `htmlcov/index.html` in your browser to view detailed line-by-line coverage information.

### Coverage Threshold

To enforce a minimum coverage percentage:
```bash
.venv/bin/python -m pytest --cov=your_module --cov-fail-under=80
```

This will cause the test suite to fail if coverage drops below 80%.

## Architecture

The package mirrors `php-remote`, class for class where Python needs it.

src/wexample_remote/common/abstract_remote.py is the contract: `get_key()`, `get_label()`, `check_status()`. It is a plain class without fields rather than a `BaseClass`, so that connectors and gateways, already attrs classes, can mix it in.

src/wexample_remote/common/remote_status.py is a src/wexample_remote/enum/remote_state.py, a message, a latency and a check date; `to_dict()` is the shape reported to consoles and screens.

src/wexample_remote/common/remote_registry.py indexes remotes by key and checks them. `check()` measures the latency and turns any exception into a down status: one broken remote must not hide the others. It is the only place the package catches everything.

src/wexample_remote/common/gateway_remote.py is the counterpart of `ApiClientRemote`. `php-remote`'s `ClientDefinition`, `ApiClientFactory` and rate limiter have none: a `wexample-api` gateway is built from its own fields, and spaces its requests itself with `rate_limit_delay`.

## Integration in the Suite

This package is part of the Wexample Suite — a collection of high-quality, modular tools designed to work seamlessly together across multiple languages and environments.

### Related Packages

The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.

Visit the [Wexample Suite documentation](https://docs.wexample.com) for the complete package ecosystem.

## Dependencies

- wexample-api: 
- wexample-helpers: >=20.1.0

## Versioning & Compatibility Policy

Wexample packages follow **Semantic Versioning** (SemVer):

- **MAJOR**: Breaking changes
- **MINOR**: New features, backward compatible
- **PATCH**: Bug fixes, backward compatible

We maintain backward compatibility within major versions and provide clear migration guides for breaking changes.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Free to use in both personal and commercial projects.

## About us

[Wexample](https://wexample.com) stands as a cornerstone of the digital ecosystem — a collective of seasoned engineers, researchers, and creators driven by a relentless pursuit of technological excellence. More than a media platform, it has grown into a vibrant community where innovation meets craftsmanship, and where every line of code reflects a commitment to clarity, durability, and shared intelligence.

This packages suite embodies this spirit. Trusted by professionals and enthusiasts alike, it delivers a consistent, high-quality foundation for modern development — open, elegant, and battle-tested. Its reputation is built on years of collaboration, refinement, and rigorous attention to detail, making it a natural choice for those who demand both robustness and beauty in their tools.

Wexample cultivates a culture of mastery. Each package, each contribution carries the mark of a community that values precision, ethics, and innovation — a community proud to shape the future of digital craftsmanship.

## Known Limitations & Roadmap

Current limitations and planned features are tracked in the GitHub issues.

See the [project roadmap](https://github.com/wexample/python-remote/issues) for upcoming features and improvements.

## Status & Compatibility

**Maturity**: Production-ready

**Python Support**: >=3.10

**OS Support**: Linux, macOS, Windows

**Status**: Actively maintained

## Useful Links

- **Homepage**: https://github.com/wexample/python-remote
- **Documentation**: [docs.wexample.com](https://docs.wexample.com)
- **Issue Tracker**: https://github.com/wexample/python-remote/issues
- **Discussions**: https://github.com/wexample/python-remote/discussions
- **PyPI**: [pypi.org/project/wexample-remote](https://pypi.org/project/wexample-remote/)

## Migration Notes

When upgrading between major versions, refer to the migration guides in the documentation.

Breaking changes are clearly documented with upgrade paths and examples.
