Skip to content

README.md

Latest commit

 

History

History
88 lines (60 loc) · 4.57 KB

README.md

File metadata and controls

88 lines (60 loc) · 4.57 KB

Ushka: A Modern Asynchronous Python Web Framework

PyPI Version Documentation Python Versions License Code Style: Black

Ushka is a modern, asynchronous Python web framework designed for simplicity, performance, and an excellent developer experience. It provides a clean, intuitive API for building web applications and APIs with minimal boilerplate.

Key Principles

  • Simplicity: Ushka's API is designed to be clean, intuitive, and easy to remember, allowing developers to focus on application logic.
  • Performance: Built on top of modern asynchronous libraries, Ushka is fast, efficient, and capable of handling high-concurrency applications.
  • Developer Experience: Features like filesystem-based routing, dependency injection, and informative error messages streamline the development workflow.
  • Flexibility: While offering sensible defaults, Ushka is highly extensible, allowing you to integrate with your preferred tools and libraries.

Features

Ushka comes equipped with a rich set of features to accelerate your development:

  • Dual Routing System:
    • Filesystem-Based Routing: Define routes simply by creating files in your routes/ directory (e.g., routes/users/profile.py maps to /users/profile).
    • Decorator-Based Routing: Explicitly define routes using Python decorators (@app.get("/users")).
  • Asynchronous Core: Built on asyncio for high performance and scalability, ready for concurrent operations.
  • Active Record ORM: A simplified, asynchronous Object-Relational Mapper based on SQLAlchemy for efficient database interactions.
  • Jinja2 Templating: Native support for the powerful Jinja2 templating engine, including asynchronous rendering and context processors.
  • Comprehensive Request & Response Objects: Easily access HTTP headers, query parameters, body data (JSON, form, raw bytes), cookies, and sessions. Flexible response handling allows returning dictionaries (auto-JSON), strings (auto-HTML), or full Response objects.
  • Dependency Injection: Automatically inject Request, Response, and configuration objects, as well as URL parameters, into your route handlers.
  • Configurability: Simple, automatic configuration management via ushka.toml, with sensible defaults.
  • Enhanced Error Handling: Informative and visually appealing error pages (404, 500) to aid debugging.
  • Rich Logging: Clear, color-coded terminal logs for better visibility into application activity.
  • Static File Serving: Easily serve static assets (CSS, JS, images) from a configurable directory.
  • CLI Tools: A command-line interface for common tasks like running the development server, managing routes, and database migrations.

Installation

Getting started with Ushka is straightforward:

pip install ushka

Quick Start

Here's a minimal example to create a simple web application using decorator-based routing:

  1. Create your application file (e.g., app.py):

    from ushka import Ushka, Request, Response

app = Ushka()

@app.get("/")
async def hello_world(request: Request) -> Response:
    return Response("<h1>Hello, Ushka!</h1>")

@app.get("/greet/[name]")
async def greet_name(request: Request, name: str) -> Response:
    return Response(f"Hello, {name}!")

if __name__ == "__main__":
    app.run()

  2. Run your application:

    python app.py

  3. Access it in your browser: Open http://127.0.0.1:8000 or http://127.0.0.1:8000/greet/World in your web browser.

For more detailed examples, tutorials on filesystem-based routing, and advanced usage, please refer to the official documentation.

Documentation

For comprehensive guides, API reference, and tutorials, visit the Ushka Documentation.

Contributing

We welcome contributions! If you find a bug, have a feature request, or want to contribute code, please check out our Contributing Guidelines.

License

Ushka is open-source software licensed under the MIT License.