Restructure the project & public API clarification from code

[ItsDrike]

This PR performs a major restructure of the mcstatus codebase with the goal of making API boundaries explicit and producing an overall less cluttered, more structured code tree.

High-level changes overview

• Internal implementation details are now consistently following proper naming, with private internals being under _ prefixed namespaces (package, module, or object names), instead of living alongside public modules.
• The old monolithic responses.py file has been split into a proper package with shared base classes, per-response type modules and a separate _raw module for TypedDict definitions.
• The communication internals (pingers, querier, bedrock/legacy status classes) were moved under the protocol package, and renamed to following the same consistent and more obvious naming scheme:
  • ServerPinger -> JavaClient
  • LegacyServerStatus -> LegacyClient
  • ServerQuerier -> QueryClient
  • BedrockServerStatus -> BedrockClient

Compatibility handling

Deprecated public modules are no longer present directly in the source tree. Instead, they live under an explicit compatibility shims package (mcstatus/_compat) and are injected into the sdist at build time via Hatchling force-include setting.

This preserves deprecated import paths accessible for end users of the library while preventing internal code from accidentally depending on them, keeping these shims from cluttering the new source tree.

Additionally, Ruff configuration was added to explicitly forbid importing from _compat internally, helping prevent accidental usage (like via LSP auto-imports).

Warning

If for some reason, someone relies on using mcstatus as a direct git submodule, this deprecation behavior will not function for them. I don't think we need to consider this as an issue, but I wanted to mention it.

This also moves the already deprecated mcstatus/status_responses.py under _compat and explicitly deprecates mcstatus/motd/transformers.py on a module import level, not just with the existing the class usage deprecation messages.

Breaking changes / Explicit public API boundaries

This PR attempts to establish a new code-style guideline for mcstatus where private internals live under _ prefixed packages or modules.

If a package itself is _ prefixed, modules inside it are considered private by default and generally do not need to be _ prefixed themselves. If a _ prefixed module exists inside a _ prefixed package, it should be considered internal to that package and should not be imported even by other mcstatus internals (except in tests).

Additionally, this PR tightens the public contract where appropriate by introducing __all__ declarations. By default, non-_ prefixed names are importable, but when __all__ is defined, only explicitly exported objects are considered public. This avoids confusion around helper constants or typing helpers (for example variables like T = TypeVar("T") or constants like MINECRAFT_COLOR_TO_RGB_JAVA). This approach allows type checkers like basedpyright to warn users when importing non-public symbols.

The changes this PR introduces in terms of public / private API separation were primarily based on what was or wasn't documented in the public API sphinx docs. That said, the documentation was actually missing some things that definitely should have been included. This PR fixes those instances too.

Specific, potentially breaking changes

• Raw response typing (TypedDict classes) now live under an internal module name and are explicitly not public API. They were never documented as public, so no backwards compatibility is provided for these, however, they were previously importable directly from mcstatus.responses, which could have lead people to think these were public types. This PR will intentionally break these imports.
• Networking internals (DNS & address logic) were moved out of the publicly reachable modules directly under mcstatus, to mcstatus._net package. Similarly, these were never intended to be public, this naming just makes that expectation clear. Again, no deprecations are provided here, people relying on these internals directly will face an immediate breakage.
• The protocol package (originally only housing the protocol/connection.py file) was renamed to _protocol, making it clear that this is an internal util.
• The client classes (previously inconsistently named, pinger/querier/status classes) were renamed and moved under the private _protocol package, with no deprecations provided for their original import paths.
• Forge response data classes (mcstatus.forge_data) were not previously explicitly documented in the docs as public. This is however very odd, as those types are useful to people that rely on type annotations (which is why all of the other response classes are public). For clean code organization purposes, this module was moved into mcstatus.responses.forge, and even though it wasn't documented to be public, compatibility shims for old mcstatus.forge_data imports will be provided.

Follow-ups and open questions

Once merged, mcstatus should bump the major version to v13 (not immediately after). That said, before this PR can be merged, several questions need to be resolved:

• Should the re-exported response classes from mcstatus/responses/__init__.py only be considered as something there for deprecation purposes, meaning using them should emit deprecation warnings, guiding users towards importing from the specific public submodules inside of the responses new package structure, or should they remain re-exported with the intention to stay re-exported? If they are to remain re-exported, should the forge response classes (which were never a part of responses.py and rather had their own file (forge_data.py) be kept reachable only udner the new mcstatus.responses.forge namespace, or should re-exports for it be included into mcstatus.responses directly? Additionally, if explicit re-exports are desired, should the structure of the package be considered entirely internal, meaning all of the submodules inside of mcstatus.responses become _ prefixed and not even meant for users to import directly?
  • Resolved: Responses will remain re-exported, forge responses will join these re-exports, fully-qualified imports of the submodules will become public API as well
• Is the approach with using __all__ to separate out public vs private parts of modules sufficient, or should this PR simply add _ prefixes for everything within the public modules that isn't supposed to be public?
  • Resolved: The PR attempts to add the _ prefix to as many internal variables in public moduels as possible, to avoid confusion from users. However, due to it's runtime behavior with star imports, __all__ will remain defined everywhere (including where it previously wasn't).
  • The definitive answer to whether or not something is public API remains the docs, the intuitive answer is whether there's _ prefix anywhere in the fully qualified path of the given symbol, __all__ does not play a strict role as to whether or not something is public API for us, but anything that is public API should be present in __all__, and anything that isn't, shouldn't be.
• Review whether additional deprecated paths should gain explicit compat shims, even if they point to now private internals before their complete removal. This might still be worth it since our public API contract was very poorly established, even if we always consider some of these parts to be mcstatus internals.
  • The main thing in question is whether the raw type-dict response types should gain deprecations.
  • Though this does also apply to true internals that people could've assumed were public, e.g. Connection,Address, pinger/status classes, ...
  • Resolved: Additional deprecations will not be included
• Is the current documentation consistent and contains everything that should be public API, and nothing that is now private API (other than on the internal docs page which is explicitly for private API)?

Merge notes

• This PR intentionally does not attempt to remove v13 deprecations. It is not meant to be a PR that prepares the mcstatus codebase for the v13 release, it just introduces the new file structure. Release preparations should be handled later, after this is merged, once we're ready to actually release v13.
• Please use the rebase merging strategy when merging.
• Do not merge the PR unless it is up-to-date with the latest commit in master (even without merge conflicts, with wide structure changes like these, the automatic merging might result in wrong import paths in various places, or badly placed newly created files, etc.)
• Do not merge if there are still fixup! commits (github's rebase strategy doesn't perform --autosquash, needs to be done manually with a force-push once ready)

[PerchunPak]

Should the re-exported response classes from mcstatus/responses/__init__.py only be considered as something there for deprecation purposes, meaning using them should emit deprecation warnings, guiding users towards importing from the specific public submodules inside of the responses new package structure, or should they remain re-exported with the intention to stay re-exported? If they are to remain re-exported, should the forge response classes (which were never a part of responses.py and rather had their own file (forge_data.py) be kept reachable only udner the new mcstatus.responses.forge namespace, or should re-exports for it be included into mcstatus.responses directly? Additionally, if explicit re-exports are desired, should the structure of the package be considered entirely internal, meaning all of the submodules inside of mcstatus.responses become _ prefixed and not even meant for users to import directly?

I think re-exports are very convenient, would keep it. Also, I don't think it is necessary to prefix all modules inside mcstatus/responses with _. The fact that forge stuff is not documented is definitely a mistake, it is a part of the public API. We should probably document those in a separate PR, but let's postpone any changes until ruff-select-all (to avoid merge conflicts)

Is the approach with using __all__ to separate out public vs private parts of modules sufficient, or should this PR simply add _ prefixes for everything within the public modules that isn't supposed to be public?

I would prefer the second option, so you don't have to remember __all__ when reading the code

[ItsDrike]

The fact that forge stuff is not documented is definitely a mistake, it is a part of the public API. We should probably document those in a separate PR, but let's postpone any changes until ruff-select-all (to avoid merge conflicts)

I have already introduced the docs for it in this PR, as it does also clarifies the public API more concretely, but I can move it out into a separate one if desired.

I think re-exports are very convenient, would keep it. Also, I don't think it is necessary to prefix all modules inside mcstatus/responses with _.

Sure, I agree

I would prefer the second option, so you don't have to remember all when reading the code

__all__ is a valid way of handling this, and a type-checker can warn about misuse if configured properly, but I can make the change, it just might make some of the internals in those modules a little harder to read compared to them having "cleaner" constants.

[PerchunPak]

I have already introduced the docs for it in this PR, as it does also clarifies the public API more concretely, but I can move it out into a separate one if desired.

We most definitely should move that into a separate PR and release it in v12

[PerchunPak]

I like the idea of test_compat.py

[PerchunPak]

Nice work!