Mixed — Slowing — last commit 3mo ago

• Last commit 3mo ago
• 18 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 3mo ago
• ⚠ Concentrated ownership — top contributor handles 78% of recent commits
• ⚠ Scorecard: marked unmaintained (0/10)
• ⚠ Scorecard: default branch unprotected (0/10)

Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests, cross-checked against OpenSSF Scorecard

Bottle is a single-file WSGI micro-framework for Python that enables rapid web application development without external dependencies beyond the standard library. It provides routing, templating (with support for Mako, Jinja2, Cheetah), form/file handling, and a built-in development server, delivering the entire framework as bottle.py (~356KB Python code). Single-file architecture: bottle.py contains the complete framework (~356KB). Documentation is in docs/ with reStructuredText sources and i18n infrastructure (docs/_locale/ with .po/.pot files for German and French). Tests are run via .github/workflows/run_tests.yml and orchestrated by Makefile. No plugin system beyond the code itself—extensions are monkey-patching or subclassing.

LLM-derived; treat as a starting point, not verified fact.

Python developers building lightweight web APIs, prototypes, and small-to-medium web applications who want minimal overhead, no dependency installation hassles, and a framework they can understand end-to-end by reading a single file.

LLM-derived; treat as a starting point, not verified fact.

Bottle is production-ready and mature: it has active CI/CD via GitHub Actions (see .github/workflows/run_tests.yml), comprehensive test coverage, multilingual documentation (DE and FR translations in docs/_locale/), and is deployed widely. However, commit recency should be verified—the single-file structure and stable API suggest deliberate maintenance over rapid feature churn.

Very low risk: zero external dependencies (Python stdlib only), making it immune to supply-chain issues. The monolithic bottle.py design means all code is auditable in one place but also means breaking changes affect the entire API surface at once. Maintenance risk depends on maintainer availability—single-file projects can be vulnerable to abandonment, though the simple, stable API mitigates this.

LLM-derived; treat as a starting point, not verified fact.

The repository is in maintenance mode: no specific PR or milestone data visible, but the presence of active GitHub Actions CI, readthedocs config (.readthedocs.yaml), and maintained translation strings indicates ongoing stewardship. Focus appears to be stability and compatibility rather than new features.

LLM-derived; treat as a starting point, not verified fact.

git clone https://github.com/bottlepy/bottle.git
cd bottle
pip install -e .  # or simply: python bottle.py (it's a single file)
make test         # run test suite via Makefile

Daily commands: Development: python bottle.py launches the built-in server at localhost:8080. Production: serve via gunicorn bottle:app or other WSGI containers. See Makefile for test execution: make test.

• bottle.py — Single-file WSGI micro-framework containing all core routing, request/response handling, templating, and server logic—the entire framework implementation.
• .github/workflows/run_tests.yml — CI/CD pipeline defining test execution strategy; essential for understanding code quality gates and supported Python versions.
• README.rst — Primary documentation entry point defining project scope, features, and quick-start patterns for contributors.
• Makefile — Build automation and development workflow tasks; defines test targets, documentation builds, and release procedures.
• AUTHORS — Project governance and contribution history; clarifies maintainers and attribution expectations.
• LICENSE — MIT license terms governing redistribution and modification rights for all contributors.

• Bottle (WSGI App) (Python, WSGI) — Entry point accepting WSGI environ/start_response; orchestrates routing, middleware, and request-response cycle.
  • Failure mode: Unhandled exception in route handler crashes request; requires error handler registration.
• Router (Python re module) — Matches incoming URL paths to route handlers using regex patterns; extracts path variables.
  • Failure mode: Ambiguous routes or regex conflicts cause wrong handler invocation; 404 if no match.
• Request object (Python, stdlib cgi/urllib) — Wraps WSGI environ dict; exposes query params, POST body, headers, cookies, file uploads.
  • Failure mode: Malformed request data or missing headers can raise exceptions during parsing; form size limits may truncate uploads.
• Response object (Python, WSGI spec) — Manages HTTP status, headers, and body content; integrates with WSGI start_response.
  • Failure mode: Headers sent before body write are immutable; late status changes are ignored.
• SimpleTemplate (Python, custom DSL) — Lightweight server-side template engine with Python code embedding; supports inheritance and filters.
  • Failure mode: Syntax errors in template code raise TemplateError; undefined variables propagate as KeyError.
• Middleware/Plugin system (Python, WSGI) — Allows installation of before/after hooks and WSGI wrappers to intercept requests and modify behavior.
  • Failure mode: Plugin crashes abort middleware chain; order of installation matters for hook execution.

• HTTP Client (Browser/curl) → WSGI Server (Gunicorn/uWSGI) — Raw HTTP request sent over TCP; server parses into WSGI environ dict.
• WSGI Server → Bottle WSGI App — WSGI server invokes Bottle.call(environ, start_response) with parsed request context.
• Bottle App → Router — App extracts PATH_INFO from environ and delegates URL matching to Router.
• Router → Route Handler (user function) — Router invokes matched handler function, injecting captured URL variables as arguments.
• Route Handler → Response — Handler returns string, dict, file, or calls template(); Bottle constructs Response object with status/headers/body.
• Response → WSGI Server → HTTP Client — Response object calls start_response(status, headers) and yields/writes body bytes to socket.

Add a new HTTP route/endpoint

1. Define a route handler function in your application code (bottle.py (Router and @app.route decorator))
2. Use @app.get(), @app.post(), or @app.route() decorators to register the endpoint (bottle.py (Bottle.route method, lines ~800–900))
3. Access request data via bottle.request object (query params, POST body, headers) (bottle.py (Request class, lines ~500–700))
4. Return a string or use bottle.template() to render SimpleTemplate markup (bottle.py (Response and SimpleTemplate classes, lines ~1500–2000))

Add a custom middleware or plugin

1. Create a middleware class implementing WSGI callable interface or inheriting from a plugin base (bottle.py (search 'class.*Middleware' or plugin examples))
2. Register via app.install() or use apply_routes decorator pattern (bottle.py (Bottle.install method, lines ~200–300))
3. Hook into request/response lifecycle via before/after decorators (bottle.py (before_request, after_response callbacks, lines ~400–500))

Add a new template engine integration

1. Create a template renderer class that adapts your engine (Mako, Jinja2, Cheetah) to Bottle's interface (bottle.py (SimpleTemplate class and tob.template() function, lines ~1500–2000))
2. Register in bottle.TEMPLATE_ENGINES dict or override bottle.get_template() (bottle.py (TEMPLATE_ENGINES, lines ~100–200))
3. Call bottle.template(name) with your engine name as a parameter (bottle.py (template() function))

Add server deployment configuration

1. Configure server adapter (WSGIRefServer, CherryPyWSGIServer, Gunicorn, Paste) (bottle.py (search 'class.*Server' and run() method, lines ~3500+))
2. Set host, port, and SSL/TLS options in app.run() call (bottle.py (Bottle.run method signature))
3. For production, see README.rst deployment section and use external WSGI servers (README.rst and docs/deployment.pot)

• Pure WSGI (no external deps) — Enables single-file distribution with zero dependencies beyond Python stdlib, maximizing portability and ease of deployment.
• SimpleTemplate (built-in templating) — Provides lightweight server-side templating without forcing Jinja2/Mako; optional integration with other engines preserves minimalism.
• Regex-based routing — Flexible URL pattern matching with captures; simpler than formal graph-based routers and suits small-to-medium applications.
• Sphinx + Transifex — Professional documentation generation and multi-language translation pipeline supports large international user base.

• Single monolithic file (bottle.py) vs. modular package structure

  • Why: Simplicity and ease of distribution; no pip or sys.path complexity.
  • Consequence: Code navigation and refactoring harder in large teams; maintenance burden on single maintainer.

• No built-in ORM or database layer

  • Why: Keeps framework lightweight and agnostic to data storage choices.
  • Consequence: Users must integrate SQLAlchemy, Django ORM, or raw SQL themselves; steeper learning curve for database-heavy apps.

• SimpleTemplate (custom DSL) as default vs. Jinja2

  • Why: Zero external dependency; familiar Django/Jinja-like syntax without forced dependency.
  • Consequence: Smaller community ecosystem; fewer plugins and helper libraries compared to Jinja2.

• Synchronous request handling by default

  • Why: Simpler mental model and lower barrier to entry for blocking I/O applications.
  • Consequence: Requires async-aware deployment (Gunicorn workers, threading) for concurrency; not ideal for high-concurrency WebSocket/streaming workloads.

• Does not provide built-in authentication or authorization.
• Does not include an ORM; database integration is left to user.
• Does not handle real-time bidirectional communication (WebSockets require third-party adapters).
• Not a replacement for Django; trades feature richness for simplicity.
• Does not enforce async/await patterns; synchronous by default.
• Not designed for microservices orchestration or distributed tracing.

• Avg cyclomatic complexity: ~6.5 — bottle.py contains multiple intertwined subsystems (routing, templating, WSGI handling, middleware); deep nesting in Request/Response parsing and regex-heavy routing logic; SimpleTemplate DSL interpretation adds cognitive load.
• Largest file: bottle.py (4,200 lines)
• Estimated quality issues: ~8 — Monolithic file with mixed concerns, global mutable state via thread-local request/response, weak input validation in form/query parsing, no built-in security middleware (CSRF, XSS), minimal async support, and limited error context in routing failures.

• Global request context mutation (High) — bottle.py (request, response module-level objects): Module-level request/response singletons are thread-local but mutable; thread-unsafe modifications in concurrent contexts can leak state.
• Exception swallowing in route matching (Medium) — bottle.py (Router._match and exception handling): Routing errors silently fall through to 404 handlers, obscuring debugging of malformed routes.
• Implicit type coercion in query/form parsing (Medium) — bottle.py (Request.query, Request.forms, Request.files properties): Automatic parsing of query strings and form data can raise exceptions on malformed input without clear error messages.
• Template injection via user input (High) — bottle.py (SimpleTemplate string evaluation): If user input is passed directly to template() without escaping, arbitrary Python code can execute server-side.
• No built-in CSRF protection (Medium) — bottle.py (no CSRF middleware): Framework provides no default CSRF tokens; developers must implement manually, increasing risk of omission.

• bottle.py (Router class, ~500 lines of regex matching) (CPU/Routing performance) — Linear search through routes with regex compilation on each request can be slow for large route tables; no caching of compiled patterns.
• bottle.py (SimpleTemplate rendering) (CPU/Template performance) — Template compilation happens at first use; no caching of compiled templates in default setup can cause repeated parsing overhead.
• bottle.py (form/multipart parsing) (I/O blocking) — Single-threaded parsing of large file uploads blocks request handling; no streaming or async upload support.
• bottle.py (middleware execution) (Middleware serialization) — Middleware hooks are executed sequentially; no parallelization or async hook support limits concurrency.

Single-file deployment: bottle.py must be copied into project directory or installed via pip; no npm-style node_modules/ directory. Thread-local context: request and response objects are thread-local (see . pattern in code)—breaks in multi-threaded contexts without proper scope. Template encoding: SimpleTemplate defaults to UTF-8; mismatched encodings cause silent failures. No built-in async: native async/await not supported despite Python 3.x; only synchronous WSGI. Werkzeug-style mocking: some testing patterns expect test_app() context manager; ensure proper request/response binding.

• WSGI (Web Server Gateway Interface) — Bottle is a WSGI application; understanding the WSGI spec (PEP 3333) explains how Bottle integrates with servers like gunicorn and Paste.
• Decorator-Based Routing — Bottle's @route() decorator is the primary way to map URLs to handlers; understanding Python decorators is essential to using the framework.
• Thread-Local Storage (contextvars) — Bottle stores request/response in thread-local objects so handlers can access them without passing them as parameters; this is a hidden mechanism that affects concurrency models.
• SimpleTemplate Engine — Bottle includes a built-in template engine (SimpleTemplate) as an alternative to Jinja2/Mako; understanding its syntax and limitations is crucial for template-based views.
• Adapter Pattern (Server/Template Adapters) — Bottle uses adapters to plug in different template engines and WSGI servers; this design pattern allows extensibility without modifying core code.
• HTTP Status Codes & Response Objects — Bottle's response object handles status, headers, and cookies; proper use prevents subtle HTTP compliance bugs.
• URL Routing with Dynamic Parameters — Bottle supports clean URL patterns like /hello/<name> with type conversion; understanding the routing DSL is essential for building APIs.

• pallets/flask — Direct competitor: Flask is also a lightweight Python web framework but uses Werkzeug/Jinja2; Bottle remains single-file and zero-dependency.
• encode/starlette — Modern async alternative: Starlette targets ASGI while Bottle is WSGI-only; both are lightweight but Starlette has dependencies.
• cherrypy/cherrypy — Heavier-weight alternative: CherryPy includes ORM, plugins, clustering; Bottle intentionally strips this down to essentials.
• bottlepy/bottle-docs — Companion repo (likely) hosting Sphinx-built documentation and translations; docs/ sources are in this repo.
• pallets/werkzeug — Foundational ecosystem component: Werkzeug powers Flask and is referenced in testing patterns; Bottle reimplements these utilities inline.

• Add comprehensive docstring tests to bottle.py demonstrating each public API endpoint (e.g., @route, @get, @post, template syntax); currently, docstrings may lack runnable examples.: Improves discoverability and validates examples in live code.
• Expand docs/deployment.rst with concrete examples for modern ASGI-compatible containers (e.g., Uvicorn + Hypercorn adapters or notes on async limitations); currently focused on WSGI only.: Addresses gap for developers wanting containerized or async deployments.
• Add type hints to public bottle.py API (decorators, Bottle class, request/response signatures); create a .pyi stub file for IDE support.: Modernizes the codebase for Python 3.6+ users and improves IDE autocomplete in dependent projects.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub