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 · Explore the documentation · Browse the API

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

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

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

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

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

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

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

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 · Explore items and properties

Get started

Install the package:

python -m pip install ewoxcore

Use a supported Python interpreter as declared in the package manifest.

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:

from requests import Response

from ewoxcore.client.http_client import HTTPClient

Create a session and make the request:

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:

from datetime import timedelta

from ewoxcore.cache.cache import Cache

Store a value with a lifetime:

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.

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 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 — Installation, imports and a runnable example.
• Configuration and services — Settings, dependency lifetimes, registration and startup.
• Serialization and transport — Data formats, models, messages and clients.
• Security — Tokens, encryption, claims and trust boundaries.
• Caching and tasks — Expiration, resource ownership and background work.
• API reference — Public modules, classes and method signatures.
• Testing and known limitations — Test scope, validation commands and documented behavior.

Browse all documentation

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 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 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

MIT licensed. See License.