Introduction to BlackSheep

BlackSheep is a modern, fast, and lightweight Python web framework for building APIs and web applications. It takes full advantage of asynchronous programming and provides developers with tools to create clean, maintainable, and high-performance APIs.

Why Choose BlackSheep?

BlackSheep is designed to allow developers to create web applications with fewer lines of code and more flexibility. Its excellent performance, simple design, and comprehensive documentation make it one of the preferred frameworks in the Python ecosystem.

Getting Started

To install BlackSheep, you can use pip:

  pip install blacksheep

Hello World Example

Let us dive into a simple “Hello World” example with BlackSheep:

  from blacksheep import Application

  app = Application()

  @app.route("/")
  async def home():
      return "Hello, World!"

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

Run this script, and your API will be available at http://localhost:8080/.

Exploring BlackSheep APIs

BlackSheep provides dozens of useful APIs that simplify building applications. Below, we will explore many APIs along with examples:

1. Routing

You can define routes with decorators like this:

  @app.route("/users")
  async def get_users():
      return [{"name": "John Doe"}, {"name": "Jane Doe"}]

2. Path Parameters

Routes can include path parameters easily:

  @app.route("/users/{user_id}")
  async def get_user(user_id: int):
      return {"user_id": user_id}

3. Query Parameters

To handle query parameters in a request:

  @app.route("/search")
  async def search_items(query: str):
      return {"query": query}

4. JSON Response

Make use of JSON responses:

  from blacksheep.messages import json

  @app.route("/api/data")
  async def get_data():
      return json({"message": "This is JSON data"})

5. Middleware

Add custom middleware for pre/post request processing:

  @app.middleware
  async def log_request(request, handler):
      print(f"Handling request: {request.url}")
      response = await handler(request)
      return response

6. Static Files

Serve static files such as CSS or JavaScript:

  app.serve_files("/static", "./static_folder")

7. Dependency Injection

Easily define and inject dependencies:

  from blacksheep import FromHeader

  @app.route("/auth-check")
  async def auth_check(authorization: str = FromHeader("Authorization")):
      return {"is_authorized": bool(authorization)}

Application Example

Here’s a more comprehensive example that combines several APIs introduced above into a small application:

  from blacksheep import Application
  from blacksheep.messages import json

  app = Application()

  # Route to get user list
  @app.route("/users")
  async def get_users():
      return [{"name": "John Doe"}, {"name": "Jane Doe"}]

  # Route with path parameter
  @app.route("/users/{user_id}")
  async def get_user(user_id: int):
      return {"user_id": user_id}

  # Route with query parameter
  @app.route("/search")
  async def search_items(query: str):
      return {"query": query}

  # JSON response example
  @app.route("/hello-json")
  async def json_response():
      return json({"greeting": "Hello, BlackSheep!"})

  # Middleware to log requests
  @app.middleware
  async def log_request(request, handler):
      print(f"Request path: {request.url}")
      return await handler(request)

  # Serve static files
  app.serve_files("/static", "./static_folder")

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

This application includes user APIs, query handling, JSON responses, middleware, and static file serving for a well-rounded BlackSheep app.

Conclusion

BlackSheep is an ideal choice for developers seeking a high-performance, modern Python web framework. With its intuitive API and excellent support for asynchronous programming, you can build robust and scalable web applications quickly.