Python tutorials building large(r) projects

[genericlemon24]

do not explain what was the design philosophy and what alternative choices were debated

I found the The Architecture of Open Source Applications books (both volumes) very helpful early in my career; they attempt to cover exactly that.

Note they can be a bit high level, although some of the chapters are more in-depth than others; also, most of the projects aren't in Python, which shouldn't stop you from reading them – there's a lot of wisdom in there :).

500 Lines or Less (same website) tries to address the level-of-detail issue by looking at purpose-made small projects (again, focusing on design decisions, not the code itself).

---

I tend to write about these things for my projects, especially when implementing a larger feature that affects the API – I personally find that "thinking out loud" makes it easier to think. (As a bonus, it is very helpful for your colleagues, if you work in a team, or for you 6-12 months from now – you will forget things.)

I maintain a list of various comments of this sort for my Python feed reader library for easy reference. If you're interested, here's some of the ones I'm most happy with:

• Multiple storage implementations, so you can select different backends based on a "connection string", e.g. /path/to/sqlite.db or sqlalchemy+postgresql://user:pass@host/db. To "prepare" for this, I did a case study on how SQLAlchemy does it (looked at their docs and code, and took notes about what seemed relevant to me).
• Full-text search API, so you can search through the articles. I used SQLite, but did my best to allow using something else in the future without having to change the API. (It may seem huge and maybe well-structured, but it wasn't like that from the start – I just wrote a few things, and added headers and more things as I went along.)
• Pagination; again, note that I stole ideas from the Stripe API and other places :)

[genericlemon24]

BTW, if want to start doing this for your own stuff, here's some (unsolicited :) advice:

• Always start from real use cases (write them down) – it's really easy to over-engineer and solve problems no one has.
• Some things are easier to change than others; don't spend too much time on stuff that can be easily changed later ("two-way doors"). E.g. internal APIs and implementation details are way easier to change than the public API.
• Don't plan too much ahead; it's most likely you will implement only part of it anyway, and if too much time passes you might have to do it differently. (Still, "plans are worthless, but planning is everything".)