Metadata-Version: 2.3
Name: ewoxcore
Version: 1.6.46
Summary: Shared runtime primitives for Ewox framework services and packages.
License: MIT
Keywords: ewox,framework,service,utilities
Author: Martin Leo Prüss
Author-email: mleopruss@gmail.com
Maintainer: Martin Leo Prüss
Maintainer-email: mleopruss@gmail.com
Requires-Python: >=3.13,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: cryptography (>=48.0.1)
Requires-Dist: joserfc (>=1.6,<2.0)
Requires-Dist: jsonpickle (>=4.1.1,<5.0.0)
Requires-Dist: lagom (>=2.7.7,<3.0.0)
Requires-Dist: numpy (>=2.3.0,<3.0.0)
Requires-Dist: pandas (>=3.0.1,<4.0.0)
Requires-Dist: python-dateutil (>=2.9.0.post0,<3.0.0)
Requires-Dist: python-i18n (>=0.3.9,<0.4.0)
Requires-Dist: requests (>=2.33.0,<3.0.0)
Requires-Dist: requests-toolbelt (>=1.0.0,<2.0.0)
Requires-Dist: shortuuid (>=1.0.13,<2.0.0)
Requires-Dist: sortedcontainers (>=2.4.0,<3.0.0)
Requires-Dist: urllib3 (>=2.6.3,<3.0.0)
Requires-Dist: validators (>=0.35.0,<0.36.0)
Project-URL: Changelog, https://github.com/mlpruss/ewox-core/blob/master/CHANGELOG.md
Project-URL: Homepage, https://github.com/mlpruss/ewox-core
Project-URL: Issues, https://github.com/mlpruss/ewox-core/issues
Project-URL: Repository, https://github.com/mlpruss/ewox-core
Description-Content-Type: text/markdown

# ewoxcore

### Give your Python services a foundation they can grow on.

A useful service needs more than an endpoint. It needs configuration that
reaches the right components, dependencies with clear lifetimes, HTTP calls
with sensible timeouts, caches that expire, tokens that can be verified, and
data that other services can understand.

As your application grows, those foundations become part of almost everything
you build. They influence how you connect integrations, organize components,
exchange messages, initialize resources and handle everyday development tasks.

**ewoxcore brings those recurring needs together in one Python package.**

It provides the shared building blocks behind Ewox applications:
configuration, dependency injection, service lifecycle, HTTP clients, caching,
serialization, token handling, logging, localization and practical utilities.
These capabilities are used across Ewox's FastAPI, Redis, Neo4j, PostgreSQL
and Elasticsearch packages.

Start with a utility in an existing project, compose a small service, or build
within the Ewox framework. Individual modules can be used without starting a
server or connecting a database.

**A common foundation for the work your services have in common.**

[Start building](docs/getting-started.md) ·
[Explore the documentation](docs/README.md) ·
[Browse the API](docs/api-reference.md)

## Build your application on shared foundations

When several services need the same capabilities, a shared implementation
gives developers familiar tools and integration points across projects.

With ewoxcore, you can bring the same configuration patterns, dependency
registrations, paging models, message envelopes and utility APIs into your
services. A developer moving between projects can recognize those foundations
and focus on the application's behavior.

The package supports several starting points:

- **An existing Python application** that needs HTTP clients, caching,
  serialization or utilities.
- **A new backend service** that needs configuration, dependency composition
  and startup coordination.
- **An integration service** that makes external requests and transforms
  structured data.
- **An Ewox application** that shares contracts with its hosting, database,
  search or messaging packages.
- **A processing tool** that works with files, CSV data, DataFrames, dates
  or collections.

You choose which capabilities to use and how they fit your application.

## What you can build with ewoxcore

### Configuration that reaches the components that need it

Load application settings from JSON files and retrieve configuration sections
as settings objects. Organize related values together and connect them to your
services through dependency registration.

Require a configuration file when startup depends on it, or allow an optional
file when your application supplies defaults.

This gives your application a clear place to assemble settings before
components begin using them. Required values and application-specific
constraints remain explicit in your settings validation.

[Explore configuration and services](docs/configuration-and-services.md)

### Dependency composition with explicit lifetimes

Register the components your application needs and resolve them through a
shared service provider.

Use singleton registration for shared instances and transient factories when
a fresh component is needed for each resolution. Register settings alongside
providers and other dependencies so your composition stays connected.

Startup contracts provide integration points for application and infrastructure
initialization. Your host retains ownership of resources and their shutdown.

This is useful when an application grows from a few directly constructed
objects into a collection of cooperating services.

[Explore dependency registration and lifecycle](docs/configuration-and-services.md)

### HTTP clients with consistent request behavior

External integrations need deliberate choices about retries, timeouts, proxies
and logging.

`HTTPClient` creates Requests sessions with configurable retry behavior and a
default timeout adapter. You can choose the HTTP methods eligible for retries,
configure retryable status codes and supply proxy settings.

Optional response metadata logging removes URL credentials, query strings and
fragments, while omitting headers and bodies. Session context managers make
resource ownership clear at the call site.

An Ewox GraphQL client is also available for services that return the supported
JSON64 response structure.

[Explore HTTP and GraphQL clients](docs/serialization-and-transport.md)

### Local caching with capacity and expiration controls

Keep frequently used values in memory with a bounded cache that supports LRU
eviction and expiration.

Store a value until it is removed or evicted, give it a relative lifetime, or
specify an absolute expiration time. Expired values are rejected on reads, and
periodic expiration processing can be enabled when needed.

The cache also supports resizing, removal, clearing and explicit shutdown. Its
context manager closes the owned expiration worker when the cache leaves scope.

Use it for process-local lookup data, temporary computed values and other
application data that benefits from reuse.

[Explore caching](docs/caching-and-tasks.md)

### Shared representations for data moving between components

Services become easier to connect when producers and consumers share the same
transport building blocks.

ewoxcore includes JSON and JSON64 helpers, serializable model support, class
registration, paging models and message envelopes. These provide common
representations for application data moving through supported Ewox integrations.

Use paging arguments to carry search, offset, page size, sorting and filters.
Use message envelopes to carry payloads alongside command and correlation
information. Register participating model classes when your transport requires
reconstruction.

The guides explain model construction, registration and trusted decoding
boundaries.

[Explore serialization and transport models](docs/serialization-and-transport.md)

### Dedicated APIs for tokens and encryption

Create and verify JWTs through `joserfc`, configure separate regular and API
signing secrets, and apply the package's registered-claim and role checks.

Regular token payloads can optionally use direct-key JWE encryption. Fernet
helpers provide text encryption and decryption, while a separate encrypted-token
envelope helper supports user-bound data with expiration.

These capabilities give applications reusable token and encryption operations.
Applications continue to own identity, tenant access, operation authorization
and key management.

[Explore security helpers](docs/security.md)

### Logging and localization through shared contracts

Use a common logging interface across application components and infrastructure
integrations. The supplied logger connects to Python logging, while the host
chooses its logging implementation and policy.

Localization support connects locale codes to translation catalogs and retrieves
translated messages through a shared provider interface.

These contracts help application components work with consistent dependencies
as your service grows.

[Explore logging and localization](docs/monitoring-localization-and-modules.md)

### Practical utilities for everyday development

ewoxcore also brings together helpers used throughout service and
data-processing code:

- **Dates and times:** parsing, formatting, timezone conversion and calendar
  operations.
- **Files and directories:** path handling, listing, naming and filesystem
  operations.
- **CSV and DataFrames:** splitting files, processing chunks, converting data
  and selecting pages.
- **Collections:** FIFO queues, typed stacks and collection helpers.
- **Conversions:** strings, numbers, booleans, dictionaries and byte
  representations.
- **Background work:** helpers for scheduling and retaining process-local
  asynchronous tasks.
- **Item structures:** item and property trees, adapters, merging, cloning
  and lookup operations.

Each guide describes the relevant inputs, behavior and ownership requirements.

[Explore utilities and collections](docs/utilities-and-collections.md) ·
[Explore items and properties](docs/items.md)

## Get started

Install the package:

```shell
python -m pip install ewoxcore
```

Use a supported Python interpreter as declared in the
[package manifest](pyproject.toml).

Import the modules your application needs. Utility use does not require full
framework startup.

### Make an HTTP request

Inside an application method, with the following imports:

```python
from requests import Response

from ewoxcore.client.http_client import HTTPClient
```

Create a session and make the request:

```python
client: HTTPClient = HTTPClient(allowed_methods=["GET", "HEAD"])

with client.session(timeout=15) as session:
    response: Response = session.get("https://example.com")
    response.raise_for_status()

    print(response.status_code)
```

The session uses the client's retry configuration and default timeout. Leaving
the context closes it.

### Cache a temporary value

Inside an application method, with these imports:

```python
from datetime import timedelta

from ewoxcore.cache.cache import Cache
```

Store a value with a lifetime:

```python
with Cache(size=100) as cache:
    cache.add("welcome-message", "Hello from ewoxcore", timedelta(minutes=5))

    print(cache.get("welcome-message"))
```

The cache enforces its capacity and checks expiration when values are read.

For a complete runnable example and guidance on choosing your first integration,
follow the [getting started guide](docs/getting-started.md).

## Grow into the Ewox ecosystem

ewoxcore supplies runtime primitives and shared contracts used by companion
packages:

- **`ewoxservicefastapi`** connects application lifecycle, authentication and
  serialization to FastAPI hosting and transport.
- **`ewoxdbredis`** uses Core cache, serialization and message contracts within
  its Redis infrastructure.
- **`ewoxdbgraph`** uses shared paging models and conversion utilities in its
  Neo4j infrastructure.
- **`ewoxdbsql`** uses shared paging models and utilities in its PostgreSQL
  infrastructure.
- **`ewoxsearches`** uses Core startup, dependency injection, logging and paging
  contracts for Elasticsearch integration.

This shared foundation helps components fit together while each package owns
its infrastructure responsibilities.

The [cross-package guide](docs/cross-package-usage.md) shows the integration
points and links to their implementations.

## Documentation that helps you make decisions

The documentation covers how to use the package, how its pieces fit together
and what behavior to expect.

Choose a path based on what you are building:

- [Getting started](docs/getting-started.md) — Installation, imports and a
  runnable example.
- [Configuration and services](docs/configuration-and-services.md) — Settings,
  dependency lifetimes, registration and startup.
- [Serialization and transport](docs/serialization-and-transport.md) — Data
  formats, models, messages and clients.
- [Security](docs/security.md) — Tokens, encryption, claims and trust boundaries.
- [Caching and tasks](docs/caching-and-tasks.md) — Expiration, resource ownership
  and background work.
- [API reference](docs/api-reference.md) — Public modules, classes and method
  signatures.
- [Testing and known limitations](docs/testing-and-limitations.md) — Test scope,
  validation commands and documented behavior.

[Browse all documentation](docs/README.md)

## Trust and resource ownership

Core's JSON64 decoders use jsonpickle and require trusted input. Base64 encoding
does not provide encryption or input validation.

Applications own their secrets, authorization rules, input validation and
resource lifecycle. The guides explain where sessions, timers, tasks and
startup resources need explicit ownership.

Read the [security policy](SECURITY.md) before integrating serialization or
token operations.

## Contribute

The package includes unit tests covering configuration, dependency resolution,
transport, caching, security, serialization, collections and utilities.

See [Contributing](CONTRIBUTING.md) for development setup and validation
commands. Report suspected security issues through the process described in
the security policy.

## Start building

Choose a capability, run an example and bring it into your application.

**Build your service on foundations you can reuse.**

[Get started with ewoxcore](docs/getting-started.md)

MIT licensed. See [License](LICENSE).

