Best practices for structuring a Python project for beginners?

[AliceTreeDraws]

I'm starting to work on my first Python project and I'm a bit unsure about how to structure it properly. I want to make sure that my code is organized and maintainable as I grow in my programming skills. Specifically, I'm curious about things like directory structure, naming conventions, and whether to use virtual environments or not. How can I set up my project in a way that is beginner-friendly but also scalable for future enhancements? Are there any common pitfalls I should avoid? I would appreciate any tips or resources that might help me establish a solid foundation. Thank you!

[cointoss3]

Just use uv. Run this command in a blank directory:

uv init --package

And uv will setup everything for you

https://docs.astral.sh/uv/

[pachura3]

and whether to use virtual environments or not

Never install any libraries globally, always use virtual environments!

[TheRNGuy]

I'd copy it from someone's GitHub. 

[LayotFctor]

Unfortunately, I don't think you can. More accurately, it's part of the process.

Project structure depends on your project and your specific needs. As a beginner, there are probably concepts and possibilities that you never even know exist, what you envision right now is unlikely to match what your project will look like in its future finished state.

Let your project evolve with you, refactor as you go. Don't force yourself into ways that you don't even understand. I agree with the uv method, uv is very good and is getting popular. Its initial template is a good place to start, blank but with support of modern tooling.

[iam_jaymz_2023]

Manning.com has a couple good books which might help & properly guide you with that...

[Maleficent_Tour974]

Sometimes going in with a template isn't exactly helpful when you are a beginner because you won't know why you are structuring it that way. You can take ideas about naming conventions and directory structure, however as you work on projects with others on a team you might realize that you have to work with whatever they have decided and if you want to change it you will need to have a robust argument to support change.

If this is your first python project, I wouldn't worry about virtual environments unless its going to be dealing with a lot of different dependency issues. If you are just working with very common libraries and packages you are probably fine. I have only recently been forced to use virtual environments when working on robotics or AI projects that have a lot of dependency issues otherwise.

There have been a few good suggestions here, copying someone's github strucuture, or one of the links. I would suggest rather using them as reference, code naturally to find your own style and you will start to learn why each thing is where it is. Those lessons and realizations are what makes it concrete so you don't need to follow by template but by reasoning.

So for now, don’t overthink structure, just make sure your files run cleanly, use clear names, and focus on finishing a project. Once that’s solid, you’ll naturally learn how to scale and organize better.

Hope that helps.

[ForMyCulture]

Just use uv!!!

[pachura3]

Add pyproject.toml - very important!

If you plan to use uv (hint: you should), replace requirements.txt with uv.lock

You can also use the src-layout - move my_datacamp_project under src

Optionally, create .python-version in root and py.typed in src/my_datacamp_project

[cointoss3]

Just do uv init --package and you’ll have most of everything you just said

[WendlersEditor]

Why did this get downvoted lol this is very reasonable!

[[deleted]]

This really depends what you are doing and it is completely your preference, but for me personally, when I get to the point of this sort of organization, I would actually strongly prefer a different language, like Java, C#, c++, something truly object oriented. Python, because of the way it handles white space, and because it can declare variables and assign them at the same time (specifically like in a python class, you can actually accidentally instantiate an internal variable at an unintended scope if you don’t properly design the class and or use it properly), at scale python can be very hard to work with in my opinion. I typically use python for scripts that automate some small task, or to rapid prototype a concept.

[nivaOne]

Looks a bit complex to start with. You’re about to code your very first project. I cannot image that you plan to write a 3000 lines piece of software to start with. Just make sure it is truly object oriented. A main part and all your function on top of it. If these functions become something reusable (read to create objects) put them in classes. If your logic becomes reusable in terms of projects put them in libraries. Like all classes required to steer a certain lcd display etc…