Project Structure

Once your environment is ready, organize your project structure. Successful project organization should follow these principles: clear structure (standardize your repository organization), modular design (separate code into logical modules with single responsibilities), test-driven development (include tests for each module), documentation (provide clear information for users and contributors), and examples (offer use cases to help users get started quickly). 

A typical structure includes several key components: a src directory containing your package modules and source code, a tests directory for test files, and a docs directory for documentation; additionally, files such as pyproject.toml for project configuration and dependencies, requirements.txt for specifying project dependencies, README.md for project overview and usage instructions, LICENSE for open-source terms, and .gitignore to exclude unnecessary files from version control. 

Essential Project Files with Examples: 

1. pyproject.toml (Modern Python projects)
   

   [build-system] 
   requires = ["setuptools>=45", "wheel"] 
   build-backend = "setuptools.build_meta" 
   
   [project] 
   name = "your-package-name" 
   version = "0.1.0" 
   description = "A brief description of your package" 
   authors = [{name = "Your Name", email = "your.email@example.com"}] 
   dependencies = [ 
       "numpy>=1.20.0", 
       "requests>=2.25.0" 
   ] 
   
   [project.optional-dependencies] 
   dev = ["pytest>=6.0", "black", "flake8"] 

   
   
2. setup.py (Alternative/Legacy approach)
    

   from setuptools import setup, find_packages 
   
   setup( 
       name="your-package-name", 
       version="0.1.0", 
       packages=find_packages(where="src"), 
       package_dir={"": "src"}, 
       install_requires=[ 
           "numpy>=1.20.0", 
           "requests>=2.25.0", 
       ], 
       python_requires=">=3.7", 
   ) 

3. src/your_package/init.py
   

   """ 
   Your Package Name 
   A brief description of what your package does. 
   """ 
   
   __version__ = "0.1.0" 
    
   # Import main classes/functions to make them available at package level 
   from .core import MainClass 
   from .utils import helper_function 
    
   __all__ = ["MainClass", "helper_function"] 

   Why init.py is required: This file marks the directory as a Python package, allowing imports like from your_package import MainClass. It also controls what gets exported when users do from your_package import *. 
   
   
4. README.md structure
   

   # Project Name 
   Brief description of what your project does. 
   
   ## Installation 
   ```bash  
   pip install your-package-name  
   ``` 
   
   ## Quick Start 
   ```python  
   from your_package import MainClass 
   
   ## Example usage 
   obj = MainClass()  
   result = obj.do_something()  
   ``` 
   
   ## Documentation 
   Link to full documentation 
   
   ## Contributing 
   Guidelines for contributors 
   
   ## License 
   MIT License (or your chosen license) 

    
   
5. Directory structure example 

# tests/test_core.py 

import unittest from my_package.core  
import add_numbers 

class TestCore(unittest.TestCase):  

   def test_add_positive_numbers(self):    
      self.assertEqual(add_numbers(2, 3), 5) 

   def test_add_negative_numbers(self): 
      self.assertEqual(add_numbers(-1, -1), -2) 

   def setUp(self): 
      """Run before each test""" 
      pass 
 
   def tearDown(self): 
      """Run after each test""" 
      pass 

Run tests:

# Run all module tests 
python -m unittest test_module 

# Run one specific test 
python -m unittest test_module.TestAbc 

# Discover and run all tests 
python -m unittest discover -s tests -p "test_*.py" 

tests/test_core.py 

import pytest from my_package.core  
import add_numbers, divide_numbers 

def test_add_positive_numbers():  
   assert add_numbers(2, 3) == 5 

def test_add_negative_numbers():  
   assert add_numbers(-1, -1) == -2 

def test_add_zero(): 
    assert add_numbers(0, 0) == 0 

def test_divide_by_zero(): 
    with pytest.raises(ZeroDivisionError): 
        divide_numbers(10, 0) 

# Install pytest 
pip install pytest 

# Run all package tests 
pytest 

# Run with coverage 
pip install pytest-cov  
pytest --cov=my_package 

# Run one test module 
pytest tests/test_core.py 

# Run one specific test 
pytest tests/test_core.py::test_add_positive_numbers 

toml 

[build-system] 
requires = ["setuptools>=61.0"] 
build-backend = "setuptools.build_meta" 

[project] 
name = "my-package" 
version = "0.1.0" 
description = "A simple Python package" 
authors = [{name = "Your Name", email = "your.email@example.com"}] 
dependencies = [ 
    "requests>=2.28.0", 
    "numpy>=1.24.0" 
] 

[project.optional-dependencies] 
dev = ["pytest>=7.0", "black>=23.0"] 
[project.urls] 
Homepage = "https://github.com/yourusername/my-package" 
"Bug Tracker" = "https://github.com/yourusername/my-package/issues" 

[project.scripts] 
my-tool = "my_package.cli:main" 

classifiers = [ 
    "Programming Language :: Python :: 3", 
    "License :: OSI Approved :: MIT License", 
] 

# Changelog 

## [0.2.0] - 2026-06-15 
### Added 
- New feature X 
### Fixed 
- Bug in Y function 

## [0.1.0] - 2026-06-01 
### Added 
- Initial release