flask-exp 0.1.0__tar.gz

flask_exp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Imran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flask_exp-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: flask-exp
+Version: 0.1.0
+Summary: Библиотека, расширяющая возможности Flask для быстрого подключения полезных функций в приложениях.
+License: MIT
+License-File: LICENSE
+Keywords: flask,extension,web,python
+Author: Podval
+Requires-Python: >=3.9,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Flask
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Requires-Dist: flask (>=2.3)
+Requires-Dist: openpyxl (>=3.1)
+Requires-Dist: sqlalchemy (>=2.0)
+Project-URL: Homepage, https://pypi.org/project/flask-exp/
+Project-URL: Issues, https://github.com/example/flask-exp/issues
+Project-URL: Repository, https://github.com/example/flask-exp
+Description-Content-Type: text/markdown
+
+# flask-exp
+
+`flask-exp` — это библиотека, расширяющая возможности Flask.
+
+Она добавляет полезные функции, которые ускоряют разработку:
+- автоматический health-check endpoint;
+- удобные JSON-ответы;
+- декоратор для маршрутов, автоматически конвертирующий `dict` в JSON.
+- импорт данных из `CSV/XLSX` в SQLAlchemy-модели по явному сопоставлению заголовков.
+- автогенерацию CRUD API-роутов по SQLAlchemy-модели.
+
+## Установка
+
+```bash
+pip install flask-exp
+```
+
+Подробная документация по использованию: [docs/USAGE.md](docs/USAGE.md)
+
+## Быстрый старт
+
+```python
+from flask import Flask
+from flask_exp import FlaskExp
+
+app = Flask(__name__)
+exp = FlaskExp(app)
+
+
+@exp.route_with_json(app, "/info")
+def info():
+    return {"service": "demo", "status": "running"}
+
+
+if __name__ == "__main__":
+    app.run(debug=True)
+```
+
+После запуска:
+- `GET /health` вернёт служебный статус;
+- `GET /info` вернёт JSON.
+
+## Импорт CSV/XLSX в SQLAlchemy
+
+Пользователь задаёт явное сопоставление `заголовок -> поле модели`.
+
+```python
+from flask import Flask
+from flask_exp import FlaskExp
+
+app = Flask(__name__)
+exp = FlaskExp(app)
+
+report = exp.exports.import_to_model(
+    file_path="users.csv",  # или users.xlsx
+    model=User,
+    mapping={
+        "Email": "email",
+        "Full Name": "name",
+    },
+    session=db_session,
+    strict=False,  # True: остановка на первой ошибке
+)
+
+print(report.created, report.failed, report.errors)
+```
+
+## Авто-CRUD API по модели
+
+Можно сгенерировать полный CRUD по SQLAlchemy-модели одной командой.
+
+```python
+routes = exp.create_crud_routes(app, User, db_session)
+```
+
+По умолчанию для модели `User` с `__tablename__ = "users"` создаются маршруты:
+- `POST /users` — create
+- `GET /users` — list
+- `GET /users/<item_id>` — get by id
+- `PUT /users/<item_id>` и `PATCH /users/<item_id>` — update
+- `DELETE /users/<item_id>` — delete
+
+Можно переопределить базовый путь:
+
+```python
+exp.create_crud_routes(app, User, db_session, base_route="/api/users")
+```
+
+## Разработка
+
+```bash
+poetry install
+poetry run pytest
+```
+
+## Публикация в PyPI
+
+```bash
+poetry build
+poetry publish
+```
+
+Для публикации через токен:
+
+```bash
+poetry config pypi-token.pypi <YOUR_PYPI_TOKEN>
+poetry publish --build
+```
+

flask_exp-0.1.0/README.md

@@ -0,0 +1,108 @@
+# flask-exp
+
+`flask-exp` — это библиотека, расширяющая возможности Flask.
+
+Она добавляет полезные функции, которые ускоряют разработку:
+- автоматический health-check endpoint;
+- удобные JSON-ответы;
+- декоратор для маршрутов, автоматически конвертирующий `dict` в JSON.
+- импорт данных из `CSV/XLSX` в SQLAlchemy-модели по явному сопоставлению заголовков.
+- автогенерацию CRUD API-роутов по SQLAlchemy-модели.
+
+## Установка
+
+```bash
+pip install flask-exp
+```
+
+Подробная документация по использованию: [docs/USAGE.md](docs/USAGE.md)
+
+## Быстрый старт
+
+```python
+from flask import Flask
+from flask_exp import FlaskExp
+
+app = Flask(__name__)
+exp = FlaskExp(app)
+
+
+@exp.route_with_json(app, "/info")
+def info():
+    return {"service": "demo", "status": "running"}
+
+
+if __name__ == "__main__":
+    app.run(debug=True)
+```
+
+После запуска:
+- `GET /health` вернёт служебный статус;
+- `GET /info` вернёт JSON.
+
+## Импорт CSV/XLSX в SQLAlchemy
+
+Пользователь задаёт явное сопоставление `заголовок -> поле модели`.
+
+```python
+from flask import Flask
+from flask_exp import FlaskExp
+
+app = Flask(__name__)
+exp = FlaskExp(app)
+
+report = exp.exports.import_to_model(
+    file_path="users.csv",  # или users.xlsx
+    model=User,
+    mapping={
+        "Email": "email",
+        "Full Name": "name",
+    },
+    session=db_session,
+    strict=False,  # True: остановка на первой ошибке
+)
+
+print(report.created, report.failed, report.errors)
+```
+
+## Авто-CRUD API по модели
+
+Можно сгенерировать полный CRUD по SQLAlchemy-модели одной командой.
+
+```python
+routes = exp.create_crud_routes(app, User, db_session)
+```
+
+По умолчанию для модели `User` с `__tablename__ = "users"` создаются маршруты:
+- `POST /users` — create
+- `GET /users` — list
+- `GET /users/<item_id>` — get by id
+- `PUT /users/<item_id>` и `PATCH /users/<item_id>` — update
+- `DELETE /users/<item_id>` — delete
+
+Можно переопределить базовый путь:
+
+```python
+exp.create_crud_routes(app, User, db_session, base_route="/api/users")
+```
+
+## Разработка
+
+```bash
+poetry install
+poetry run pytest
+```
+
+## Публикация в PyPI
+
+```bash
+poetry build
+poetry publish
+```
+
+Для публикации через токен:
+
+```bash
+poetry config pypi-token.pypi <YOUR_PYPI_TOKEN>
+poetry publish --build
+```

flask_exp-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["poetry-core>=1.9.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "flask-exp"
+version = "0.1.0"
+description = "Библиотека, расширяющая возможности Flask для быстрого подключения полезных функций в приложениях."
+readme = "README.md"
+license = "MIT"
+authors = [
+  "Podval"
+]
+keywords = ["flask", "extension", "web", "python"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: Flask",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries",
+]
+packages = [{ include = "flask_exp", from = "src" }]
+
+[tool.poetry.dependencies]
+python = ">=3.9,<4.0"
+flask = ">=2.3"
+sqlalchemy = ">=2.0"
+openpyxl = ">=3.1"
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=8.3"
+ruff = ">=0.6"
+
+[tool.poetry.urls]
+Homepage = "https://pypi.org/project/flask-exp/"
+Repository = "https://github.com/example/flask-exp"
+Issues = "https://github.com/example/flask-exp/issues"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]

flask_exp-0.1.0/src/flask_exp/__init__.py

@@ -0,0 +1,5 @@
+from .extension import FlaskExp
+from .exports import Exports, ImportReport
+
+__all__ = ["FlaskExp", "Exports", "ImportReport"]
+__version__ = "0.1.0"

flask_exp-0.1.0/src/flask_exp/exports.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import csv
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterable
+
+from openpyxl import load_workbook
+
+
+@dataclass
+class ImportReport:
+    created: int = 0
+    failed: int = 0
+    skipped: int = 0
+    dry_run: bool = False
+    errors: list[dict[str, Any]] = field(default_factory=list)
+
+
+class Exports:
+    def import_to_model(
+        self,
+        *,
+        file_path: str | Path,
+        model: type,
+        mapping: dict[str, str],
+        session,
+        strict: bool = True,
+        dry_run: bool = False,
+        commit: bool = True,
+        encoding: str = "utf-8-sig",
+    ) -> ImportReport:
+        path = Path(file_path)
+        headers, rows = self._read_rows(path, encoding=encoding)
+        self._validate_mapping(headers=headers, model=model, mapping=mapping)
+
+        report = ImportReport(dry_run=dry_run)
+
+        for row_number, row in rows:
+            payload = {model_field: row.get(source_header) for source_header, model_field in mapping.items()}
+            try:
+                if dry_run:
+                    model(**payload)
+                else:
+                    with session.begin_nested():
+                        instance = model(**payload)
+                        session.add(instance)
+                        session.flush()
+                report.created += 1
+            except Exception as exc:
+                report.failed += 1
+                report.skipped += 1
+                report.errors.append(
+                    {
+                        "row_number": row_number,
+                        "error": str(exc),
+                        "row": row,
+                        "payload": payload,
+                    }
+                )
+                if strict:
+                    if not dry_run:
+                        session.rollback()
+                    raise ValueError(f"Import failed on row {row_number}: {exc}") from exc
+
+        if not dry_run and commit:
+            session.commit()
+
+        return report
+
+    def _validate_mapping(self, *, headers: list[str], model: type, mapping: dict[str, str]) -> None:
+        missing_headers = [header for header in mapping.keys() if header not in headers]
+        if missing_headers:
+            missing = ", ".join(missing_headers)
+            raise ValueError(f"Headers not found in file: {missing}")
+
+        missing_model_fields = [field_name for field_name in mapping.values() if not hasattr(model, field_name)]
+        if missing_model_fields:
+            missing = ", ".join(missing_model_fields)
+            raise ValueError(f"Model fields not found: {missing}")
+
+    def _read_rows(self, path: Path, *, encoding: str) -> tuple[list[str], Iterable[tuple[int, dict[str, Any]]]]:
+        extension = path.suffix.lower()
+        if extension == ".csv":
+            return self._read_csv(path, encoding=encoding)
+        if extension == ".xlsx":
+            return self._read_xlsx(path)
+        raise ValueError("Only .csv and .xlsx files are supported")
+
+    def _read_csv(self, path: Path, *, encoding: str) -> tuple[list[str], Iterable[tuple[int, dict[str, Any]]]]:
+        with path.open("r", encoding=encoding, newline="") as file:
+            reader = csv.DictReader(file)
+            if reader.fieldnames is None:
+                raise ValueError("CSV file must contain a header row")
+            headers = [str(field) for field in reader.fieldnames]
+            rows = [(index, row) for index, row in enumerate(reader, start=2)]
+        return headers, rows
+
+    def _read_xlsx(self, path: Path) -> tuple[list[str], Iterable[tuple[int, dict[str, Any]]]]:
+        workbook = load_workbook(path, read_only=True, data_only=True)
+        worksheet = workbook.active
+        raw_rows = worksheet.iter_rows(values_only=True)
+
+        try:
+            header_row = next(raw_rows)
+        except StopIteration as exc:
+            raise ValueError("XLSX file is empty") from exc
+
+        if not header_row:
+            raise ValueError("XLSX file must contain a header row")
+
+        headers = [str(value).strip() if value is not None else "" for value in header_row]
+        rows = []
+        for row_number, values in enumerate(raw_rows, start=2):
+            row = {header: value for header, value in zip(headers, values)}
+            rows.append((row_number, row))
+
+        workbook.close()
+        return headers, rows

flask_exp-0.1.0/src/flask_exp/extension.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+from functools import wraps
+from typing import Any, Callable
+
+from flask import Flask, jsonify, request
+from sqlalchemy.inspection import inspect as sqlalchemy_inspect
+
+from .exports import Exports
+
+
+class FlaskExp:
+    def __init__(self, app: Flask | None = None, *, health_endpoint: str = "/health") -> None:
+        self.health_endpoint = health_endpoint
+        self._initialized = False
+        self.exports = Exports()
+        if app is not None:
+            self.init_app(app)
+
+    def init_app(self, app: Flask) -> None:
+        if self._initialized:
+            return
+
+        app.extensions["flask-exp"] = self
+        self._register_health_endpoint(app)
+        self._initialized = True
+
+    def _register_health_endpoint(self, app: Flask) -> None:
+        endpoint_name = "flask_exp_health"
+        if endpoint_name in app.view_functions:
+            return
+
+        @app.get(self.health_endpoint)
+        def flask_exp_health() -> tuple[dict[str, str], int]:
+            return {"status": "ok", "library": "flask-exp"}, 200
+
+    def json_response(self, payload: dict, status_code: int = 200):
+        response = jsonify(payload)
+        response.status_code = status_code
+        return response
+
+    def route_with_json(self, app: Flask, rule: str, **options):
+        def decorator(func: Callable):
+            @wraps(func)
+            def wrapper(*args, **kwargs):
+                result = func(*args, **kwargs)
+                if isinstance(result, dict):
+                    return self.json_response(result)
+                return result
+
+            app.add_url_rule(rule, endpoint=options.pop("endpoint", None), view_func=wrapper, **options)
+            return wrapper
+
+        return decorator
+
+    def create_crud_routes(
+        self,
+        app: Flask,
+        model: type,
+        session,
+        *,
+        base_route: str | None = None,
+        endpoint_prefix: str | None = None,
+    ) -> dict[str, str]:
+        mapper = sqlalchemy_inspect(model)
+        primary_keys = [column.key for column in mapper.primary_key]
+        if len(primary_keys) != 1:
+            raise ValueError("CRUD auto-router supports models with a single primary key")
+
+        primary_key = primary_keys[0]
+        all_columns = [column.key for column in mapper.columns]
+        writable_fields = [field for field in all_columns if field != primary_key]
+
+        resource = base_route or f"/{model.__tablename__}"
+        detail_resource = f"{resource}/<item_id>"
+        endpoint_base = endpoint_prefix or model.__name__.lower()
+
+        endpoints = {
+            "create": f"{endpoint_base}_create",
+            "list": f"{endpoint_base}_list",
+            "get": f"{endpoint_base}_get",
+            "update": f"{endpoint_base}_update",
+            "delete": f"{endpoint_base}_delete",
+        }
+
+        def serialize(instance) -> dict[str, Any]:
+            return {column: getattr(instance, column) for column in all_columns}
+
+        @app.post(resource, endpoint=endpoints["create"])
+        def create_item():
+            payload = request.get_json(silent=True)
+            if not isinstance(payload, dict):
+                return self.json_response({"error": "JSON body must be an object"}, 400)
+
+            data = {field: payload[field] for field in writable_fields if field in payload}
+            instance = model(**data)
+            try:
+                session.add(instance)
+                session.commit()
+            except Exception as exc:
+                session.rollback()
+                return self.json_response({"error": str(exc)}, 400)
+
+            return self.json_response(serialize(instance), 201)
+
+        @app.get(resource, endpoint=endpoints["list"])
+        def list_items():
+            items = session.query(model).all()
+            return self.json_response({"items": [serialize(item) for item in items]})
+
+        @app.get(detail_resource, endpoint=endpoints["get"])
+        def get_item(item_id):
+            instance = session.get(model, item_id)
+            if instance is None:
+                return self.json_response({"error": "Not found"}, 404)
+            return self.json_response(serialize(instance))
+
+        @app.put(detail_resource, endpoint=endpoints["update"])
+        @app.patch(detail_resource, endpoint=f"{endpoints['update']}_patch")
+        def update_item(item_id):
+            payload = request.get_json(silent=True)
+            if not isinstance(payload, dict):
+                return self.json_response({"error": "JSON body must be an object"}, 400)
+
+            instance = session.get(model, item_id)
+            if instance is None:
+                return self.json_response({"error": "Not found"}, 404)
+
+            for field in writable_fields:
+                if field in payload:
+                    setattr(instance, field, payload[field])
+
+            try:
+                session.commit()
+            except Exception as exc:
+                session.rollback()
+                return self.json_response({"error": str(exc)}, 400)
+
+            return self.json_response(serialize(instance))
+
+        @app.delete(detail_resource, endpoint=endpoints["delete"])
+        def delete_item(item_id):
+            instance = session.get(model, item_id)
+            if instance is None:
+                return self.json_response({"error": "Not found"}, 404)
+
+            session.delete(instance)
+            session.commit()
+            return self.json_response({"status": "deleted"})
+
+        return {
+            "resource": resource,
+            "detail_resource": detail_resource,
+            "endpoints": endpoints,
+        }