Metadata-Version: 2.4
Name: apep-webservice-forge
Version: 0.1.0
Summary: A Python web framework built on FastAPI and Jinja2 that eliminates boilerplate, enforces clean architecture, and lets you go from idea to working MVP in a single night.
Project-URL: Homepage, https://soss.page
Project-URL: Repository, https://github.com/soss-community/apep_webservice_forge
Project-URL: Bug Tracker, https://github.com/soss-community/apep_webservice_forge/issues
Project-URL: Documentation, https://github.com/soss-community/apep_webservice_forge/tree/main/docs
Project-URL: Contact, https://github.com/soss-community
Author: sora7672
License: SOSS Module & Package License (SOSS-MPL) v1.0
        ==============================================
        Copyright (c) 2026 sora7672 & SOSS Community
        Website: https://soss.page
        Organization: https://github.com/soss-community
        
        NOTE: This license may be updated over time.
        Always refer to the latest version at: https://github.com/soss-community
        The version included in this repository was current at time of release.
        
        ---
        
        ACCEPTANCE
        
        By incorporating this package or module into your software, code, or project in any form,
        you confirm that you have read and understood the terms of this license.
        Usage constitutes full acceptance of all conditions stated below.
        
        ---
        
        1. PERMITTED USE
        
           This package/module may be used freely by anyone, for private or commercial purposes,
           subject to the conditions of this license.
        
        2. NO MODIFICATION & DISTRIBUTION
        
           Modification of the original source files is not permitted.
           Modified versions of this package/module may not be redistributed in any form.
        
           Exception:
           You may create child classes or wrapper implementations that extend
           the functionality through inheritance or composition. These must be clearly marked
           as separate works and must not replace or repackage the original.
           This exception exists to allow external verification of behavior, if an issue
           arises in a child class, it can be clearly distinguished from the original.
        
        3. CREDITS & ATTRIBUTION
        
           Any software, project, or codebase that uses this package/module must clearly
           credit it in one of the following locations:
           - A credits section in the README
           - An About screen or page within the software
           - Any other clearly visible location within the project documentation
        
           The credit entry must include:
           - A link to the SOSS community page: https://soss.page
           - The name of the module/package (e.g. "taipan-logger")
           - If multiple SOSS packages/modules are used, all must be listed individually.
        
        4. COMMERCIAL USE
        
           Commercial use of this package/module is explicitly permitted.
           In addition to the credit requirement above, commercial users are strongly encouraged
           to open a discussion on the official GitHub repository with the tag:
           "Using this package/module for my software"
           including the name of their software.
           This will be read and closed by the maintainer.
           This does not replace the credit requirement.
        
        5. ISSUE REPORTING
        
           Issues, bugs, and feature requests are managed exclusively via the official
           GitHub repository of the respective package/module.
           Before reporting an issue, you must have read the README and documentation,
           and must understand the intended purpose of the software.
        
        6. SUPPORT
        
           No official support is provided by the developers or maintainers.
           If you or your organization wish to offer support for this package/module,
           including commercial support, you may apply via the SOSS community page:
           https://soss.page
        
           Approved support providers will be listed there publicly.
           No individual or organization may present themselves as an "official" support
           provider without being listed on the SOSS community page.
        
           Listings may be revoked at any time if quality standards are not maintained.
           The affected party will be notified and the listing updated accordingly.
        
        7. NO MONETIZATION
        
           This package/module is not for sale under any circumstances, regardless of the offer.
        
           Any new maintainer who takes over this project must agree to the same conditions.
           Monetization of this package/module by any maintainer is strictly prohibited.
        
           In the event of a violation, third parties are entitled to pursue legal action
           against the maintainer and to seek the appointment of a new maintainer
           who agrees to these conditions.
        
        8. LEGAL & DISPUTE RESOLUTION
        
           In the event of a dispute arising from improper use or violation of this license,
           all legal costs shall be borne by the party found to be in violation.
           This applies internationally to the extent permitted by applicable law.
        
        9. NO WARRANTY & NO LIABILITY
        
           This package/module is provided "as is", without warranty of any kind.
           The maintainers and contributors make no guarantees regarding functionality,
           fitness for a particular purpose, or absence of errors.
        
           We are human, mistakes can happen. We do our best to keep the code clean and reliable,
           but we accept no liability for any damages, data loss, or other consequences
           arising from the use of this software.
        
        ---
        SOSS-MPL is part of the Sora Open Source Software standard.
        All SOSS-licensed projects must include this license file unchanged.
        Website: https://soss.page
        Organization: https://github.com/soss-community
License-File: LICENSE
Keywords: architecture,asgi,backend,boilerplate,business-logic,clean-architecture,clean-code,consent,fastapi,frontend-backend-split,fullstack,gdpr,html,jinja2,layered-architecture,no-boilerplate,python-web,routing,scaffolding,seo,separation-of-concerns,server-side-rendering,templating,uvicorn,web-framework
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.12
Requires-Dist: aiofiles
Requires-Dist: fastapi
Requires-Dist: jinja2
Requires-Dist: ladon-clear-exceptions-n-warnings
Requires-Dist: uvicorn
Provides-Extra: taipan
Requires-Dist: taipan-logger; extra == 'taipan'
Description-Content-Type: text/markdown

# Apep Webservice Forge

> A Python web framework built on FastAPI and Jinja2 that eliminates boilerplate, enforces clean architecture,
> and lets you go from idea to working MVP in a single night.

![Python](https://img.shields.io/badge/python-3.12%2B-blue)
![License](https://img.shields.io/badge/license-SOSS%20Community-green)
![Version](https://img.shields.io/badge/version-0.1.0-orange)
[![Community](https://img.shields.io/badge/community-soss.page-purple)](https://soss.page)
<img width=75px height=20 src="https://komarev.com/ghpvc/?username=soss-community-apep&color=763eab&style=flat-round&label=Views:" />

---

## Is This Framework Right for You?

Before diving in, read the **[Framework Decision Guide](./docs/decision_guide.md)** to find out whether Apep  
fits your use case - or whether you need something else entirely.  

---

## The Problem

Every time you start a new Python web project, you hit the same wall.  
FastAPI handles routing. Jinja2 handles templates. But neither knows the other exists.  
Connecting them - plus SEO, security headers, consent management, static files, and error handling -  
means writing the same boilerplate every single time.  

Apep solves that. You define what pages you need, and the framework wires everything together.  
Routes, templates, business logic stubs, HTML structure, SEO tags, error handling - all of it.  
You write the parts that are unique to your project. Apep handles everything else.  

**Developers should develop. Not administer.**  
The goal: have an idea on Friday evening, have a working backend by Saturday morning.  

---

## Features

- **Enforced architecture**  
  Bad architectural decisions are structurally impossible, not just discouraged.  
  Business logic, backend logic, and frontend logic are always separated. The framework makes sure of it.  

- **Automatic page generation**  
  Pass a list of routes. Get registered endpoints, HTML templates,  
  and scaffolded business logic files. No manual wiring, no repeated setup.  

- **Head / Top / Content / Bottom split**  
  Configure your navigation and footer once.  
  Every page gets the correct structure automatically. Only the content area changes per page.  

- **Frontend-to-backend validation**  
  Missing template variables are caught before the page renders.  
  The server stays up. You see exactly what is wrong and where.  

- **SEO out of the box**  
  `sitemap.xml`, `robots.txt`, Open Graph tags, canonical URLs, and robots meta  
  are generated automatically based on your page configuration.  

- **GDPR-compliant consent management**  
  Built-in consent banner, ready to use, no custom implementation needed.  

- **Large macro library**  
  Ready-to-use Jinja2 macros for the most common UI components,  
  available in every template without any imports.  

- **Stage awareness**  
  A visible indicator in dev and staging mode so you always know where you are.  
  Automatically removed in production.  

---

## We Fail Fast, Loud, and Hard

When something is wrong, Apep does not silently continue with broken state.  
It raises an error immediately, tells you exactly what failed and where, and stops.  
This is intentional. A loud failure during development costs seconds.  
A silent failure in production can cost hours to days debugging.  

---

## What is Apep?

*Apep is an alternate name for Apophis - the Egyptian serpent of chaos and infinite complexity.  
Look closer and the pattern is simple. One entry, one exit, everything in between is just structure.*  

*That is what Apep does. It takes what looks complex - a web backend with routing, templating, configuration,  
SEO, consent management, security headers - and turns it into a straight line.*  

*Like all projects in this ecosystem, the name follows the snake theme. Because we write Python.*  

---

## Before You Start

Apep runs as a Python ASGI application. Not every hosting provider supports this.  
Before building with Apep, check whether your provider lets you run a Python application.  
VPS, dedicated servers, and Docker-based hosting work without issues.  
Shared hosting that only serves static files or PHP will not work.  

---

## Installation

```bash
pip install apep-webservice-forge
```

This installs Apep together with everything it needs to run:  

- **[FastAPI](https://github.com/fastapi/fastapi)** - routing  
- **[Jinja2](https://github.com/noirbizarre/jinja2)** - templating  
- **[Uvicorn](https://github.com/Kludex/uvicorn)** - ASGI server  
- **[Ladon Clear Exceptions and Warnings](https://github.com/soss-community/ladon_clear_exceptions_n_warnings)** - structured,  
  human-readable error output built specifically for this ecosystem  

You do not need to install or configure any of these manually.  

**New to Python web development?**  
Read the **[PyCharm Setup Guide](./docs/pycharm_setup.md)** first.  
It walks you through everything - from installing Python to your first running page, step by step.  

### Optional: Taipan Logger

By default, Apep runs silently unless you connect your own logging callbacks.  
If you want automatic, structured tracing of every framework call without writing any logging code yourself,  
install the Taipan Logger - also built for this ecosystem:  

```bash
# As part of the Apep install
pip install apep-webservice-forge[taipan]

# Or standalone
pip install taipan-logger
```

See the **[Logging and Error Handling Guide](docs/logging_and_error_handling.md)** for details on both options.  

---

## Quickstart

```python
import apep_webservice_forge as apep
import uvicorn

apep.configure_misc(website_main_url="https://soss.page")
apep.use_all_apep_pages()

webservice = apep.mass_create_pages(
    ["/sora7672", "/open-source", "/soss-community"],
    create_fastapi_routes=True,
    create_missing_html=True
)

if __name__ == "__main__":
    uvicorn.run(webservice, host="0.0.0.0", port=8000)
```

Three routes. Three HTML templates generated automatically. Server running.  
Open the generated HTML files, add your content, reload - done.  

This is one of several ways to set up an Apep project.  
Each feature has its own guide - check the **[Documentation](#documentation)** section below.  

> **Note:** Apep uses lazy initialization. After starting the server, always open at least one page  
> in the browser to verify everything has started up correctly.  

---

## Configuration

Apep comes with sensible defaults. Nothing blocks startup if left unconfigured.  
When you are ready to set up your project properly, all settings live in Python.  

**Before you try to configure Apep via a config file - read why that is deliberately not an option.**  
The **[Configuration Guide](./docs/configuration.md)** explains the security reasoning behind this decision  
and lists every available setting with its default value and what it does.  

---

## Documentation

| Guide | What it covers |
|---|---|
| [PyCharm Setup](./docs/pycharm_setup.md) | Project setup, venv, packages, Uvicorn run config |
| [Decision Guide](./docs/decision_guide.md) | Is Apep the right tool for your use case? |
| [Configuration](./docs/configuration.md) | All settings, defaults, stages, JS banner, consent banner |
| [Architecture](./docs/architecture.md) | How business logic, backend logic, and frontend logic are separated |
| [Auto Creator](./docs/auto_creator.md) | mass_create_pages, create_single_page, scaffolding |
| [Manual Pages](./docs/manual_pages.md) | Manual ContentPage setup, query parameters, business logic |
| [Templates and Macros](./docs/templates_and_macros.md) | Page structure, base templates, macros |
| [Apep Loader](./docs/apep_loader.md) | Script loader, CSS/JS deduplication and load order |
| [Styling](./docs/styling.md) | Colors, spacing, typography, customization |
| [SEO and Consent](./docs/seo_and_consent.md) | sitemap.xml, robots.txt, consent state |
| [Logging and Error Handling](./docs/logging_and_error_handling.md) | Error pages, exception hooks, callback registration, Taipan Logger |
| [Response Types](./docs/response_types.md) | PageResponse, StatusResponse, FileResponse |

---

## What This Is Not For

| Use Case | Why it does not fit |
|---|---|
| Complex browser-based applications | Apep renders on the server. Dynamic SPAs belong in React, Vue, or similar. |
| REST API backends without a frontend | Use plain FastAPI. Apep adds overhead you do not need. |
| Projects requiring an ORM | Apep has no ORM. Database access lives in your business logic layer. |
| Admin interfaces | Deliberately excluded. Build them explicitly if you need them. |
| Node.js or TypeScript stacks | Apep is Python-first. No JavaScript runtime is involved server-side. |

---

## Compatibility

Tested and confirmed working versions are listed in the **[Configuration Guide](./docs/configuration.md)**.  
Always check there for the currently supported versions before updating dependencies.  

Apep is developed and tested on Windows. Linux and macOS should work but are not officially supported yet.  

---

## License

SOSS Community Package License (SOSS-CPL).  
The full license text is included in this repository.  
Latest version always at: [github.com/soss-community](https://github.com/soss-community)  

### Packages we ship

- [Jinja2](https://github.com/noirbizarre/jinja2)  
- [FastAPI](https://github.com/fastapi/fastapi)  
- [aiofiles](https://github.com/Tinche/aiofiles)
- [Ladon Clear Exceptions n' Warnings](https://github.com/soss-community/ladon_clear_exceptions_n_warnings)  
- [Taipan Logger](https://github.com/soss-community/taipan-logger)  - (Optional)

### Fonts we ship

Inter - Copyright 2020 The Inter Project Authors - SIL Open Font License 1.1  
JetBrains Mono - Copyright 2020 JetBrains s.r.o. - Apache License 2.0  

---

## Community and Contributing

Part of the Sora Open Source Software community.  
Contribution guidelines, issue tracking, and community discussion:  
[github.com/soss-community](https://github.com/soss-community)  

> **Author:** [sora7672](https://github.com/sora7672)  
> **Organization:** [soss-community](https://github.com/soss-community)  
> **Website:** [soss.page](https://soss.page)