Repository navigation
Non-idiomatic File Naming Conventions (Java-style Class/File Names) #93
Description
Please describe your feature request.
Hi Paddle team,
Thanks for your work on the Python SDK—it's great to see official support for Paddle in the Python ecosystem.
I noticed that the file structure of the SDK tends to follow a Java-style convention, where each file is named after the main class it contains (e.g., Client.py, Resources.py). While this makes sense in Java, it's not idiomatic in Python.
According to PEP 8, Python prefers:
Lowercase file/module names, optionally with underscores (e.g., client.py, response_parser.py)
Refactoring the file naming to match Python conventions would improve readability, maintainability, and alignment with community standards. It would also help developers integrate the SDK more easily into existing Python projects.
Would this be something you're open to updating? I’d be happy to assist or contribute a PR if helpful.
Describe your solution.
No response
Describe alternatives you have considered.
No response
Additional context
No response
Activity
CCXLV commentedon Apr 23, 2025
It's been a few days without a response, so I decided to take matters into my own hands. Two days ago, I tried to fix the issues I mentioned, but after looking at the codebase, I realized it’d be better to start fresh. So, I built this library.
I don't mean to be harsh, but the codebase seemed pretty far from Python standards, and making all the changes would’ve been tough and could’ve caused bigger issues.
Right now, the library only supports the Products endpoint of the Paddle API (that's as far as I got in the last two days), but it's built with
httpxand works both asynchronously and synchronously.I’ll keep working on it to add support for the rest of the Paddle API over time.
heymcgovern commentedon Apr 30, 2025
Hey, Michael from the DX team here 👋
Thanks for your patience while we got back to you on this. Great to hear that you're interested in contributing to the Paddle ecosystem.
We took an initial look at your library and there's a few interesting takeaways for us:
Async support is a great addition. We've had a request for it before Feature request: Async support #87 and it's on our radar but not at the top of our priority list yet. Seeing your implementation gives us a good reference point.
We're going to investigate switching from black/flake8 to ruff.
Your use of Pydantic for model validation is interesting. We're using dataclasses with type hints, but your approach might offer some additional benefits we should explore.
File naming is a valid point, and something we can look into for the future. When we initially launched the SDK, we had to balance compatibility with an existing community SDK and consistency within the project (see PEP 8). Changing file naming now would be a breaking change and could create substantial work for our existing SDK users, so it's something we need to carefully evaluate before moving forward.
You mentioned that you feel the codebase is far from Python standards. Other than file naming standards, could you share what you feel isn't up to standards? We're keen to learn how we can make our SDK more friendly for Python devs.
-- Michael
CCXLV commentedon Apr 30, 2025
For example, in the
paddle_billing/Entitiesdirectory, there are exactly 503 Python files, each containing only a single class. From my perspective as someone who wants to contribute to the project, this makes it difficult. I have to navigate through a large number of files and directories just to get some basic understanding of what’s going on.I have a good example of how it might look like in my repo, I know it's still early and not complete, but it should give you an idea of the approach I'm suggesting.
Nekidev commentedon Dec 28, 2025
I was considering opening an issue for the same problem. It's quite inconsistent and unintuitive to use the SDK as it is currently. I struggled a while to find out where things were located due to this. It took me some time to figure out you can't do
Because
Eventis a module and you actually wantEvent.Event, it's certainly not pythonic. Needing to have one import per line is not clean too, given entities could be all grouped under apaddle.entitiesmodule or justpaddleon its own.Additionally, the webhook verifier is not really pythonic either, which is what I'm mostly interested in at the moment. It seems to require the webhook secret to be passed as a
Secret(secret: str)instead of a string, but the definition of such secret does nothing other than wrapping a string?The verifier takes a request-like object, but given it doesn't need much more than the signature header and the request body, why not just
.verify(signature=..., body=...)? That way it's framework-agnostic and doesn't depend on what you consider "request-like".As @CCXLV mentioned above, Pydantic is similar to dataclasses and has support for them by default, yet this SDK doesn't seem to be compatible with it. It's not a deal-breaker, but certainly a QoL thing.
Async support is also quite necessary, the web server environment is usually very async-friendly and specially when talking to a rest API. Not having async support is quite a deal-breaker in my case, for example, given I end up having to wrap most things from scratch anyways.
About breaking changes, I understand it would be a big overhaul on the SDK, yet I think it would relieve quite some struggle when using the SDK. @CCXLV's library looks, at first sight (looking at its README), way closer to what a standard python SDK looks like.
CCXLV commentedon Dec 28, 2025
@Nekidev the library is not finished though, should I continue working on it to make it fully support the API?
Nekidev commentedon Dec 28, 2025
@CCXLV I haven't given it any in-depth analysis other than checking its README, though it looks like the concept is well-done. I'll probably try to work with this SDK due to the API schema types even if they're rusty, though I do believe this SDK should be more python-like.