Best Practices for Python Desktop Application Project Structure

The Importance of Project Structure

When developing non-trivial Python desktop applications, a well-designed project structure is crucial for long-term maintenance and team collaboration. A good project structure should meet several core requirements: ease of maintenance, IDE friendliness, suitability for source control branching and merging, and easy generation of installation packages. Python, as a flexible language, offers multiple choices in project structure, but this also means developers need to make informed decisions.

Core Directory Structure Design

Based on community practices and project requirements, we recommend the following directory structure approach:

project_name/
├── bin/
│   └── project_script
├── project_name/
│   ├── __init__.py
│   ├── core.py
│   └── test/
│       ├── __init__.py
│       └── test_core.py
├── lib/
│   └── external_c_libraries.c
├── doc/
│   └── documentation_files
├── config/
│   └── configuration_files
├── setup.py
└── README.md

Source Code Organization Strategy

Source code should be placed in a package directory named after the project. This design avoids using generic src or lib directories, making the code organization structure clearer. For example, if the project is named myapp, the main Python modules should be located under the myapp/ directory.

In Python, packages are defined by directories containing an __init__.py file. This file can be empty or contain package initialization code. Here's a simple package structure example:

# myapp/__init__.py
"""
MyApp main package
"""
__version__ = "1.0.0"

# myapp/core.py
def main_function():
    """Application core functionality"""
    return "Hello from core"

Startup Script Management

Application startup scripts should be placed in the bin/ or scripts/ directory. These scripts should remain concise, with their main function being to import and call appropriate functions from the main package. On POSIX systems, script files should not include the .py extension, while on Windows systems the extension should be retained.

#!/usr/bin/env python3
# bin/myapp

import sys
import os

# Add project root directory to Python path
sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))

from myapp.core import main

if __name__ == "__main__":
    main()

IDE Configuration File Handling

Different IDEs generate their own configuration files, such as PyCharm's .idea/ directory, VS Code's .vscode/ directory, etc. These files should be placed in the project root directory but typically should not be committed to version control systems. They can be ignored using a .gitignore file.

# .gitignore
.idea/
.vscode/
*.kpf
__pycache__/
*.py[cod]
*$py.class

Test Code Organization

Unit tests and acceptance tests should be organized as a sub-package of the project package. This design allows test code to easily access the modules being tested and also facilitates running tests after installation. Test files should follow the test_*.py naming convention.

# myapp/test/__init__.py
"""
Test package
"""

# myapp/test/test_core.py
import unittest
from myapp.core import main_function

class TestCore(unittest.TestCase):
    def test_main_function(self):
        """Test core functionality"""
        result = main_function()
        self.assertEqual(result, "Hello from core")

if __name__ == "__main__":
    unittest.main()

Non-Python Data File Handling

Configuration files, resource files, and other non-Python data should be placed in dedicated directories such as config/, data/, or resources/. When accessing these files in code, use paths relative to the project root directory.

import os
import json

def load_config():
    """Load configuration file"""
    config_path = os.path.join(
        os.path.dirname(__file__), 
        '..', 
        'config', 
        'app_config.json'
    )
    with open(config_path, 'r') as f:
        return json.load(f)

C++ Extension Module Integration

For Python extension modules that need to be written in C++, the relevant source code should be placed in the lib/ directory. These extension modules can be configured for compilation and installation through the setup.py file.

# setup.py
from setuptools import setup, Extension

module = Extension(
    'myapp._native',
    sources=['lib/native_module.c'],
    include_dirs=['lib/include']
)

setup(
    name='myapp',
    ext_modules=[module],
    # Other configurations...
)

Dependency Management and Virtual Environments

Python projects should use virtual environments to isolate dependencies. We recommend using Python's built-in venv module to create virtual environments and managing project dependencies through a requirements.txt file.

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Linux/Mac: source venv/bin/activate
# Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Development Tool Integration

Modern Python development should integrate code quality tools such as code formatters, static analysis tools, and testing frameworks. We recommend using black for code formatting, ruff for code checking, and pytest as the testing framework.

# requirements-dev.txt
black>=23.0.0
ruff>=0.1.0
pytest>=7.0.0
pytest-cov>=4.0.0

# Run code formatting
black myapp/

# Run code checking
ruff myapp/

# Run tests
pytest myapp/test/

Version Control and Release Management

Projects should use Git for version control and manage releases through tags. The setup.py file should be properly configured with package information and dependencies to facilitate distribution through PyPI.

# setup.py
from setuptools import setup, find_packages

setup(
    name="myapp",
    version="1.0.0",
    packages=find_packages(),
    install_requires=[
        "requests>=2.25.0",
        "click>=8.0.0"
    ],
    entry_points={
        "console_scripts": [
            "myapp=myapp.core:main"
        ]
    },
)

Summary and Best Practices

A good Python project structure should follow these principles: keep it simple and intuitive, facilitate navigation, support modular development, and be easy to test and maintain. By organizing related functionality in appropriate packages and modules, using standard directory structures, and integrating modern development tools, you can significantly improve project maintainability and development efficiency.

In practical development, project structure should be adjusted according to specific needs. For small projects, the structure can be simplified; for large, complex projects, more granular module division may be necessary. Most importantly, maintain consistency to ensure all team members can understand and follow the project's organizational structure.