Describe python "project" structure

Would it be possible for somebody very briefly describe what each folder in python file structure does ?

I can deduct that “src” contains source files…

What I do not get is - what contains GUI (windows) _ and what contains code which does processing and why.

I like to know this when I add new function to the application - what goes in what sub folder.

Screenshot from 2023-07-04 13-47-29|294x500](upload://l41RW9Mqo9XcoWiWg2wsfFQLMlE.png)

There is no set “python file structure”, and folders do not “do” anything at all except to contain files. If you are using certain tools or libraries, they might expect specific things to be in specific folders; see the documentation for details.

However, there are some basic recommendations for how to organize a Python project, that are useful for packaging and distribution (this means: making it possible for others to install your code easily, either from e.g. a Github repository or from uploading it to PyPI. This is much too complex to explain in a single post, but there is a full guide offered by the Python Packaging Authority:

Somehow your image didn’t show.

Looks like you are talking about nanovna-saver/src/NanoVNASaver at main · NanoVNA-Saver/nanovna-saver · GitHub

The folders are specific to that project. That’s just how they chose to organize their functions. Other projects will use a completely different structure.

Thanks for your reply. I am well aware there is no common way to organize Python project.

Confirming that was not the reason why I posted this.

I am trying to add function / class to the
project and was looking for explanations on HOW is current project organized.

I am just reading current project and its layout looks as it has GUI code and then "action / process " code in separate folders.

I just need confirmation that my guess is “close enough”…
and it is relatively unimportant where the code came from and what it does.

Out of curiosity, if you don’t already know the answer to your
question, how can you be sure what information is required to arrive
at an answer?

As for an answer: If you’re going to be contributing your additions
back to the community which maintains the software you’re altering
then they’re the ones in the best position to indicate the most
optimal placement. If you’re not planning to contribute it to them,
then you can pretty much put it wherever is most convenient for you.
It’s a subjective question after all, so pretty much any answers you
get are going to be opinions… how do you decide whose opinion is
the best one?

how can you be sure what information is required to arrive
at an answer?

My answer is very simple - I work with what I have and make the best guess.
If the source covers / answers everything 100 % I would pick another hobby…

Since the software I am trying to “reverse engineer” does not include anything describing the project folders I am pretty much on my own. The “stuff” on giothuiub is also pretty much abandoned… Yes there are some “fixes” but that doe sno help much.

As I said - I like to add another function / functionality to the project and since it is my first attempt using Python I am just curios how to oganoize / where to add my stuff.

I prefer to add my stuff in a separate place , such as a new folder etc.

Yes , I can add “new project” using PyCharm but that is very minimal as far as organization and using folders.

Basically I would like to have this

initialize project - such as clone etc.
subfolder - version control

project classes – including main
subfolder - classes additions

class functions / process


That is what I like to see as "project structure ".

If your preference is to put your additional Python module (*.py)
files in a subdirectory, that can definitely be made to work. Keep
in mind that each directory containing module files is itself an
“import package” in Python parlance. That is implicit behavior by
default, but you can make it explicit by adding (even an empty) file in the directory containing your module files.
For example:


Then anything using these can access their contents by using the .
operator in import statements, like (just one of many ways):

import originalpackage.mysubpackage.mymodule

If you want a solid structure into which you put your own code, I’d recommend having a look at Django - it’s one of the most popular Python web frameworks and tends to work in that sort of style. But not everything does, so you’ll much more commonly find that the structure of a project is defined by the project, not by the language or framework you’re using.

Python is not Java; we don’t need shackles and boilerplate and rigid structure.

This is a pretty far-fetched and unjustified accusation to level at someone for merely observing that there exists a diverse range of needs for the huge Python ecosystem [1], as a whole.

  1. Which spans: finance, medicine, several engineering disciplines, academic research, HPC computing, web development, SAAS infrastructure, data science and ETL,… just off the top of my head. ↩︎

1 Like

I give up…

I can’t speak to Pycharm or other IDEs since I stick to command line
tools (comfortable Unix/POSIX user since the 80s), but generally
speaking rearranging the files in an existing project has
implications on how the objects defined within those files and the
modules or import packages they comprise are accessed, even from
within other files in that same codebase. Any reorganization made
without taking necessary edits of those files’ contents into account
will quite possibly alter its internal API in ways which render the
whole nonfunctional.

Also, “you can organize your project however you like” isn’t
necessarily the same thing as “you must write spaghetti code and
bake in your job security.” The point was that you’re allowed to,
for example, have multiple classes in a single file (or not even use
classes at all if you don’t want, Python doesn’t mandate a specific
coding paradigm like OO or pure functions or whatever), split things
up into arbitrary groups in different files or directories, et
cetera, stitched together with simple import statements. The
language doesn’t prevent you from organizing your work poorly, but
it also doesn’t try to force someone else’s opinions on you as to
what well-organized code means.

In case it hasn’t been clear in your reading so far, the Python
language is a scripting language, so more akin to languages like
Perl, PHP or Bourne/Korn/C Shell than to something like C++ or Java.
It’s design goals focus more on readability, flexibility and
comprehensive toolsets without being overly opinionated on style
(syntactically relevant elements aside) or insisting on specific
coding patterns.

There was a reason for asking about python " project " structure.
The application I am working with starts with “about” info , which I do not see when I run it as “normal” from executable , not using IDE.

After “about” it runs “main”…
Apparently that is OK, but a little confusing when trying to logically “step” through the application.

I was looking for some structure / sequence of code so I can find where is the logical place to add my code.

But if there is no such thing as logical flow of code my reverse engineering process is pretty futile.

I also had a few headaches with finding out “Linux executable” in the python code and using PyCharm IDE.

Using Eclipse was easy - it asks for Linux executable BEFORE cloning the software , but cloning using PyCharm has no such option. That means I have to know which is actually executable…

Despite all these challenges, I am making progress, mainly thanks to this forum.
It really helps to have support like this forum - most of my questions are not of “read the manual” variety.



I suppose another way to look at it is that there’s no inherent
“project” concept in Python. There are import packages and modules
and objects therein, but anything at a higher “project” level is a
construct of your IDE, source control system, distribution package
manager, or whatever, not Python itself.

I can maybe clarify this a little, at least.

  1. Any Python file can be a program’s entry point, because whenever the interpreter loads a Python source file it is executed from top to bottom,
  2. If you run a Python file directly, like with python in a terminal, the interpreter sets a variable __name__ to a sentinel string value ”__main__”. A module can use this to tell the difference between whether it is executing because it was imported, or is executing because it was called as a script. You will commonly see the lines:
if __name__ == “__main__”:
    # do stuff

Near the bottom of a stand-alone script file. The code there can be thought of similarly to the “main(argc, argv)” from some compiled languages.

  1. If a package folder contains a file called (there is one of these in the project screenshot), you can tell Python to execute the package with python -m package_folder_name_here, and the code in package_folder_name_here/ will be loaded and evaluated first. In this case you can think of the entire file as the “main” function.
  2. Because any module file could be used as an entry point, when building a binary executable, it is up to the tool that creates the executable to set which module or function will serve as the entry point. You would need to look at the project’s build configuration to determine what function is executed from a packaged binary. Similarly, the setuptools packaging system has specific configuration for “entry point scripts” that are installed when a package is installed using pip. That tool is discussed in the packaging guide linked earlier; if the project you’re studying uses setuptools look for it’s configuration files to see what entry points the package defines.

Once you identify an entry point, remember that modules are executed in order to import them, so the file containing an entry point function will be evaluated top to bottom - including any module it imports - then the function will be called.

This is likely why you are seeing the debugger step into the “about” code before the main function runs, even though you don’t observe that behavior when launching the program normally. The about module is imported into the file that serves as the entry point, and will execute at the time it is imported before the rest of the entry point file.

Though the main function is necessary in most of those languages, and the “if name is main” dance in Python is ONLY necessary for something that is both a script and an importable module. Which is why you frequently WON’T see those lines at the bottom of a script.

This is technically accurate and a very good point. [1]

  1. I think I overemphasize this based on my own experience? I have worked with a lot of people who have been told this once and now do it by rote whether they actually need it or not! ↩︎

Yep, that’s the problem: doing things by rote without actually needing them, because you think it’s what you “should do”. That creates boilerplate, possibly incorrect, and almost certainly unnecessary. One of Python’s beauties is that you need only do the things that you actually need, not things you got taught in your Comp Sci 101 class as “always do this”.

I believe the last two replies just opened a “bag of worms” for me.

After the last posts , It is no longer a simple( C ) “file” - it is script , function , module , package… then the most confusing "import " . I really need to read a "Python for dummies " booK.

I was ready to add a new class to the code and now I have no clue HOW and where

  • as a package , module , script , function ?? Perhaps PyCharm will guide me …

Instead of trying to dive in and understand someone else’s large project, follow a tutorial for the Python language (for example, the one on the Python website from the start, and learn to write your own code starting from scratch. Then you don’t have to worry about understanding a lot of existing code, because that code isn’t there to bother you.

Great idea, however, I am not fond of starting to learn from “command / script” . I got spoiled using IDE which hides most of the starting items - in current state I can start "creating a project " , even when there is no such term in python. That is all of my choosing, but my approach "creates some unnecessary questions " which are probably covered in "command /script " documentation. It may sound stupid - but I have no desire to learn all the “neat stuff” of python - I just want to improve some existing code. ( basically some more data verification / calculation …) So far most of my problems stem from lack of documentation / comments of the code I am trying to “improve”.
I have to be very careful not to irreparably destroy the current code.