Projects and portfolio

Python Project Structure for a First Repository

Organize a small Python repository with a README, an entry point, sample inputs, and tests. Know when a package layout helps.

For a small Python project, put the README and entry script at the repository root, sample inputs in examples/, and tests in tests/. Use a package when multiple callers need the same code. Consider a src/ layout when you need to test the installed package separately from your working copy.

Keep a single-purpose script easy to run

For a small report tool, put the script and README at the top level. Keep a synthetic sample in an examples directory, and document one command that starts from the project root. Test the command in a fresh copy of the repository.

Decide how the program gets its input path. The current directory is a useful default when the caller chooses a file they own. A sample shipped with the project can use an explicit path documented in the README. That distinction avoids surprises when someone runs the script from their home folder.

Separate reusable logic from the entry script

When a terminal command, a test, and a GUI all need the same calculation, give that calculation a clearly named module. Let those callers decide how to display errors. This keeps the validation rule in one place and preserves the ability to test it without a window or terminal.

As the package grows, decide where to place the importable code. If you need to test an installed package separately from your working copy, read the guide to src layouts and imports. For a small standalone tool, a direct link from the README to the script and its fixtures is often enough.

Put tests beside the behavior they verify in the reader's mind

A tests folder can mirror major concepts such as report creation and input validation without matching every code file one for one. Start with tests that use clear values and describe a promise. A test named “rejects duplicate reservation” is easier to reason about than “test function 2”.

Store only stable sample data in version control. Generated reports, build outputs, and local virtual environments usually belong outside the project's committed inputs. A reviewer should be able to tell whether a data file came from the example or from a run.

Change the layout only when it buys something

If imports fail only from your editor, first compare the interpreter and the working directory. Moving all the files can leave the real problem unresolved. If tests import a local file that never makes it into an install, a packaging test is a better first correction than adding more path adjustments.

Finish with a clean-checkout test someone else can perform. It should document environment setup, one run command, expected result, and the test command. Add a new directory when it makes two responsibilities easier to distinguish.

Once readers can find the files, document the command someone should run first.

Sources and further reading

Related reading

Browse Projects and portfolio · Explore project tutorials

Search PythonProjects.org