Skip to main content

Environemnt As A Software

Package codecov

Build an environment with a database and a REST API.

Requirements

  • Python 3.12
  • PostgreSQL 13.4
  • Redis 6.2.6 (optional but recommended)

Initial setup

Create a database in PostgreSQL:

create database database_name;

Create a virtual environment and install the dependencies:

python -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Set the environment variables:

POSTGRES_URI=<SQL_DATABASE_URI>

# macOS only
OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES

# Optional for Redis
REDIS_URI=<REDIS_URI>

Initialize alembic:

# alembic_init.py
from eaasy.extensions.migration import init
from argparse import ArgumentParser, Namespace as ArgumentNamespace

def get_arguments() -> ArgumentNamespace:
    parser = ArgumentParser(description='Alembic migration helper')
    parser.add_argument('sql_url', metavar='sql_url', type=str, help='SQLAlchemy URL')
    parser.add_argument('--path', '-p', metavar='path', type=str, help='Alembic path', default='src/alembic')
    parser.add_argument('--tables-folder', '-t', metavar='tables_folder', type=str, help='Tables folder', default='src/tables')

    args = parser.parse_args()

    if not args.sql_url:
        raise Exception('SQLAlchemy URL is required')

    return args

if __name__ == '__main__':
    args = get_arguments()
    init(args.sql_url, args.path, args.tables_folder)

Launch the script to build the alembic folder:

python alembic_init.py <SQL_DATABASE_URI> # --path src/alembic (optional)

Create a table:

# src/tables/user.py
from eaasy import BaseEntity, Audit
from sqlalchemy import Column, String

class UserProperties:
    firstName = Column(String, nullable=False)
    lastName = Column(String, nullable=False)
    email = Column(String, nullable=False, unique=True)


class User(BaseEntity, UserProperties, Audit):
    __tablename__ = 'users'

And add it to the src/tables/__init__.py file:

# src/tables/__init__.py
from .user import User

__all__ = ['User']

Run the migration:

alembic revision --autogenerate -m "Create users table"
alembic upgrade head

Run the application

Create a main module:

# app.py

from eaasy import Eaasy, GunEaasy
from eaasy.extensions import build_model, build_resource
from src.tables.user import User, UserProperties

api = Eaasy(
    name=__name__,
    title='API',
    version='1.0',
    description='A simple API',
    doc='/swagger'
)

# Create models for User resource (GET, POST and PUT)
user_ns, get_model = build_model(User)
user_ns, upsert_model = build_model(UserProperties, namespace=user_ns)

# Build and register resource
build_resource(User, user_ns, get_model, upsert_model)

# # Add namespace to API
api.add_namespace(user_ns)

app = api.get_app() # Required if you want to perform flask operations

if __name__ == '__main__':
    options = {
        'bind': '%s:%s' % ('0.0.0.0', '8080'),
        'workers': 1
    }
    GunEaasy(app, options).run()

Run the application:

python app.py
# or
gunicorn app:app
# or
flask run

Features

Custom endpoints

By default the build_resource method build a resource with these enabled endpoints:

  • get_all -> GET /entity/ # Get all entities
  • post -> POST /entity/ # Create new entity
  • get_by_id -> GET /entity/id:int # Get entity by id
  • put -> PUT /entity/id:int # Edit entity by id
  • delete -> DELETE /entity/id:int # Delete entity by id

You can disable one or more endpoints by setting to False the correspoing key, for instance:

# Build resource without get_by_id endpoint
build_resource(User, user_ns, get_model, upsert_model, get_by_id=False)

File exports

Enable an Excel download by adding the file_export flag when building the resource:

build_resource(
    User,
    user_ns,
    get_model,
    upsert_model,
    file_export=True,
    file_headers=['id', 'firstName', 'lastName', 'email'],
    file_name='users.xlsx'
)
  • GET /entity/file/ streams an .xlsx attachment with every entity returned by get_all.
  • file_headers is optional. When omitted, columns are inferred from the collected entities.
  • file_name is optional. The filename defaults to <EntityName>.xlsx.

Excel generation uses openpyxl.

File imports

You can let clients upload spreadsheet data and upsert rows by enabling file_import:

build_resource(
    User,
    user_ns,
    get_model,
    upsert_model,
    file_import=True,
    file_preview=True,
    file_unique_fields=['email'],  # Columns used to detect duplicates
    file_field='file',             # Optional form field name
    file_sheet='Sheet1'            # Optional sheet override
)
  • POST /entity/file/ accepts a multipart form upload containing an .xlsx file.
  • Rows are converted into dictionaries using the header row.
  • If file_unique_fields is provided (or defaults to ['id'] when the column exists), matching rows are updated while new rows are created.
  • Multiple columns are supported in file_unique_fields (e.g. ['name', 'category']) and must uniquely identify a row.
  • The endpoint responds with the number of created and updated records.
  • Imported rows go through the same callbacks as the REST endpoints: on_post fires for every created row and on_put for every updated one. A callback that raises stops the import at that row, leaving the previous rows written; define on_post_fail / on_put_fail to absorb the error and carry on.
  • POST /entity/file/preview/ accepts the same payload and returns the parsed headers plus rows in JSON for a pre-import review.

Spreadsheet parsing also relies on openpyxl; ensure the dependency is installed before enabling the feature.

Callbacks

You can add callbacks to the resources:

def after_post(data):
    print(data.firstName) # 'data' represent the model of the object created after the POST request

build_resource(User, user_ns, get_model, upsert_model, on_post=after_post)

Available callbacks:

  • on_post
  • on_put
  • on_delete

on_post and on_put mean "a record was created / updated", whichever path wrote it: they are invoked by POST and PUT as well as by every row of a file import.

Each callback accepts an optional <name>_fail counterpart (e.g. on_post_fail) that receives the exception. Without it, the failure is wrapped in a CallbackError and the request returns a 500. CallbackError exposes event, original and data, so the failing hook and the underlying exception stay reachable:

from eaasy.extensions import CallbackError

Limit rate

API requests can be limited by the number of requests in an interval of time.

NOTE: the application should be running with Redis properly configured. See environment variables in Initial setup section.

You can enable limiter using enable_limiter parameters:

api = Eaasy(
    name=__name__,
    title='API',
    version='1.0',
    description='A simple API',
    doc='/swagger',
    enable_limiter=True
)

And set the limit for all methods:

build_resource(User, user_ns, get_model, upsert_model, limit='5 per minute')

Or specify a limit for each method:

build_resource(User, user_ns, get_model, upsert_model, get_all_limit='5 per minute')

Available arguments:

  • get_all_limit
  • get_by_id_limit
  • post_limit
  • put_limit
  • delete_limit

Logger

By providing logger parameter in Eaasy class you can:

api = Eaasy(
    logger=True # Configure default logger
)
api = Eaasy(
    logger=custom_logger # Or provide your own logger
)

And you can also extract and wherever you want (especially if you want to use the default one):

logger = api.logger # This raises an exception if not configured

OpenIDConnect (from flask_oidc)

Same for the OpenIdConnet instance:

api = Eaasy(
    oidc=True # Configure default OIDC
)
api = Eaasy(
    oidc=OpenIDConnect(app) # Or provide your own OIDC (OpenIDConnect from flask_oidc package only)
)

Extract and use it:

oidc = api.oidc # This raises an exception if not configured

Refer to flask_oidc docs for OpenIDConnect configuration (make sure that the installed version matches the version described in the docs).

You can set the accept_token decorator for all methods:

build_resource(User, user_ns, get_model, upsert_model, oidc=app.oidc)

Or specify the accept_token decorator for each method:

build_resource(User, user_ns, get_model, upsert_model, get_all_oidc=app.oidc)

Available arguments:

  • get_all_oidc
  • get_by_id_oidc
  • post_oidc
  • put_oidc
  • delete_oidc

To introduce other decorators please create your own resource and set the required decorators.

Refer to flask_restx docs for decorators configuration (make sure that the installed version matches the version described in the docs).

Metadata

Release files for eaasy 0.5.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for eaasy 0.5.2
File Size Uploaded Provenance Actions
eaasy-0.5.2.tar.gz 23.5 kB With provenance Details for eaasy-0.5.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for eaasy 0.5.2
File Interpreter ABI Platform Actions
eaasy-0.5.2-py3-none-any.whl Python 3 none any Details for eaasy-0.5.2-py3-none-any.whl

Total release size: 44.8 kB

Release files / eaasy-0.5.2.tar.gz

Download URL eaasy-0.5.2.tar.gz
Size 23.5 kB
Tags Source
SHA-256 checksum
How to use checksums
174ec6840c275451ad1b8849ee8478e047560d5b46fc81f01dc43c743e1dcd7c
BLAKE2b-256 checksum
How to use checksums
1eeb22f8d1959cfebb14bcbc2a46247510c711e148d5aac9055609a7c57e39bd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Release files / eaasy-0.5.2-py3-none-any.whl

Download URL eaasy-0.5.2-py3-none-any.whl
Size 21.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
16f3944ed3272c2b7edcf339db0e11958c096835733f651c5f09e29ac6eec9f6
BLAKE2b-256 checksum
How to use checksums
b7d30f6aa9c45cc7bae0c840ccd82df6bb0fe58e4a8fc2995549bf9c0f437a7e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Security for eaasy 0.5.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for eaasy-0.5.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.5.2 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page