apep-webservice-forge 0.2.1

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.

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.

---

Is This Framework Right for You?

Before diving in, read the Framework Decision Guide 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.

---

Add on to the readme:

Stop building infrastructure. Start building your idea. Most projects don't fail because of bad ideas. They fail because of bad defaults, mixed-up layers, and setups that don't scale. By default, nothing is crawlable, nothing leaks, nothing gets indexed that shouldn't - you explicitly decide what goes public. The architecture enforces itself, so layers stay clean without you thinking about it. Start with a simple page today, grow into something complex tomorrow, without ever rewriting what you already built.

---

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.

• Layered Styling System
  A complete CSS design system ships with every project: seven ordered layers from reset to custom tags,
  full light and dark mode out of the box, a color attribute system (txtcolor, bgcolor, bordercolor)
  that maps every color variable directly to HTML, and custom HTML tags for layout and content
  that need no JavaScript and no class names.

• 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

pip install apep-webservice-forge

This installs Apep together with everything it needs to run:

• FastAPI - routing
• Jinja2 - templating
• Uvicorn - ASGI server
• Ladon Clear Exceptions and 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 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:

# 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 for details on both options.

---

Quickstart

Make sure you created in your project folder the static and the templates directory.
Otherwise it will throw an exception telling you that it could not find the directories.

import apep_webservice_forge as apep
import uvicorn

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

apep.mount_static_dir("/static")

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

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

Important Note on uvicorn settings and browser security: If you don't use a proper host ip or port, it can happen that your browser RANDOMLY starts blocking your JS! Always make sure to use a valid ip.

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 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 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	Project setup, venv, packages, Uvicorn run config
Decision Guide	Is Apep the right tool for your use case?
Configuration	All settings, defaults, stages, JS banner, consent banner
Architecture	How business logic, backend logic, and frontend logic are separated
Auto Creator	mass_create_pages, create_single_page, scaffolding
Manual Pages	Manual ContentPage setup, query parameters, business logic
Templates and Macros	Page structure, base templates, macros
Apep Loader	Script loader, CSS/JS deduplication and load order
Styling	Where CSS belongs, decision guide, replacing and extending styles
Styling System	All CSS layers, tokens, color variables, attribute mapping
Default HTML Styling	How naked HTML elements are styled by default
SEO and Consent	sitemap.xml, robots.txt, consent state
Logging and Error Handling	Error pages, exception hooks, callback registration, Taipan Logger
Response Types	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.
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

Packages we ship

• Jinja2
• FastAPI
• aiofiles
• Ladon Clear Exceptions n' Warnings
• 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

Author: sora7672
Organization: soss-community
Website: soss.page