bancho.py

bancho.py is a backend for a private osu! server designed for developers of all experience levels. It aims to provide a reliable, feature-rich, and easy-to-maintain implementation of an osu! server that is simpler to deploy and modify than the Akatsuki.gg technology stack, while maintaining the ability to handle high player concurrency.

To run bancho.py or contribute to the project, refer to the bancho.py wiki.

bancho.py is a backend-only project and does not include a website. To provide a user interface, you can use one of the following frontend options:

• bancho-web.ts (Recommended): A modern React + TypeScript frontend built on the bancho.py v2 API. It includes leaderboards, player profiles, beatmap pages, clans, player search, and website-based registration/login (with optional captcha support). This is officially supported by the bancho.py team.
• guweb (Alternative): A long-standing Python-based frontend maintained by the community. It interacts directly with the bancho.py database.

bancho.py is strictly a backend and does not include a built-in website. To provide a user interface, you should use one of the following compatible frontends:

• bancho-web.ts (Recommended): A modern React + TypeScript frontend built on the bancho.py v2 API. It includes features like leaderboards, player profiles, beatmap pages, clans, player search, and website-based registration/login (with optional captcha support). This is maintained by the bancho.py team.
• guweb (Alternative): A long-standing, community-maintained Python frontend that communicates directly with the bancho.py database.

The primary goal is to match official osu! server behavior.

• Default Behavior: Always aim to match official osu! behavior unless it adds significant complexity for minimal gain.
• Intentional Divergence: If you must diverge from official behavior, you must leave a code comment explaining why. This is critical for future migrations or data backfills.
• Operational Impact: Be cautious with large migrations or backfills, as many projects may be running forks or direct versions of the master branch and need to stay synchronized.

Testing should focus on application logic rather than Python internals. Follow these patterns:

• Test Style: Prefer the arrange, act, assert pattern over heavy use of test helpers.
• Dependency Injection over Monkeypatching: Unit tests should use explicit composition. If a test requires patching imports, globals, or classmethods, the production code likely needs better dependency boundaries.
• Test Doubles: Use small, local test doubles with clear intent:
  • _FakeX: For a cooperative dependency with visible state.
  • _FailingX: For a dependency intended to trigger an error path.
• Scope: Use small unit tests for critical logic and integration tests for broad flows. Do not let broad integration tests replace focused coverage of critical rules.
• Refactoring: Refactor code to make it testable, but keep refactors scoped to the behavior under test.

bancho.py is strictly a backend server and does not include a website. To provide a user interface for your server, you can use one of the following options:

1. bancho-web.ts (Recommended): A modern React + TypeScript frontend built on top of the bancho.py v2 API. It includes features like leaderboards, player profiles, beatmap pages, clans, player search, and web-based registration/login (with optional captcha support). This is maintained by the bancho.py team.
2. guweb (Alternative): A community-maintained Python-based frontend that accesses the bancho.py database directly.

Service functions should use domain verbs that align with osu! terminology. This makes the orchestration of business logic readable and explicit.

Recommended patterns:

• Use verbs like submit_score, save_replay_file, announce_first_place, persist_score_submission_stats, or unlock_achievements.
• Avoid vague names: Do not use finalize_*, prepare_*, or update_*_state if the function performs multiple unrelated decisions or side effects.
• Orchestration: A high-level service should clearly show the main domain steps in order.

bancho.py is a backend service and does not include a built-in website. To provide a user interface, you can use one of the following frontends:

1. bancho-web.ts (Recommended): A modern React + TypeScript frontend built on the bancho.py v2 API. It includes leaderboards, player profiles, beatmap pages, clans, player search, and web registration/login (with optional CAPTCHA support). This is maintained by the bancho.py team.
2. guweb (Alternative): A community-maintained Python-based frontend that interacts with bancho.py by directly reading from and writing to its database.

When submitting Pull Requests:

• Coherence: Keep each PR coherent. Large PRs are acceptable if they move a single theme forward and are fully covered by tests.
• Traceability: Every changed line should be directly related to the PR's purpose.
• Comment Preservation: Do not remove existing comments when refactoring unless they are no longer accurate.
• Review Workflow: Do not amend review follow-up commits unless requested; instead, add new commits so that review deltas remain easy to inspect.

To maintain type safety and clarity, follow these guidelines:

• Use Concrete Types: Prefer real types (e.g., TypedDict, enums, protocols, or small models) over generic dict[str, Any] when a value has a known shape.
• Minimize Type Suppression: Avoid using cast() and type: ignore. These should only be used at hard third-party boundaries.
• Handle Third-Party Weak Typing: Instead of spreading casts through the app, use a public stubs package, a small wrapper, an adapter, or a local stub.
• Domain States: Use full enum.Enum for domain states instead of magic integers or partial constants.
• Sentinel Values: Use explicit sentinel values like Unset instead of relying on None if None carries specific semantic meaning.

The server is an ASGI application powered by uvicorn. You can start the application by executing the main.py script. When running, the application will:

1. Configure logging via app.logging.
2. Display a startup dialog via app.utils.display_startup_dialog().
3. Launch the ASGI app located at app.api.init_api:asgi_app.

Configuration such as the host, port, and debug mode (which enables reload) is pulled from app.settings. The server also injects a custom bancho-version header into responses.

python3.11 main.py