Python Scripting Best Practices 2025 Edition

Preface

You can feed this article directly to an AI, put it in an AI role definition, or use it directly as a prompt.
That way, you just state your requirements and let the AI write the scripts.

Overview

• Pursue simplicity and clarity: scripts should be straightforward.
• Use functions, constants, and proper import practices to logically organize your Python scripts.
• Use data structures like enumerations and data classes to efficiently manage script state.
• Enhance interactivity with command-line arguments, and use logging and libraries like Rich for structured feedback to improve robustness.
• Create self-contained, shareable scripts by handling dependencies inline using PEP 723.

Fundamentals

• Add comments at the beginning of scripts to describe functionality, author, version, and change history
• Avoid hardcoding — hardcoded values make scripts inflexible
• Use named constants to improve clarity and make scripts easier to read and maintain
• Use an entrypoint (if __name__ == "__main__":) to separate executable code from importable definitions
• Use the Python tool — uv:
  • A replacement for pip, pip-tools, poetry, pyenv, twine, virtualenv, and more.
  • UV can run Python scripts with support for adding dependencies and executing scripts.
  • UV supports adding dependencies using inline metadata and can run scripts without manually installing dependencies.
  • UV installation command: $ curl -LsSf https://astral.sh/uv/install.sh | sh
• Use a Shebang line: #!/usr/bin/env -S uv run --script
• Sensitive information: never hardcode passwords/keys — use environment variables or configuration files

External Libraries and Dependencies

• Integrate third-party libraries when needed to leverage specialized functionality or simplify complex tasks.

• Declare and manage script dependencies within the file using standards like PEP 723 for reproducibility.

  # /// script
  # requires-python = ">=3.13"
  # dependencies = [
  #   "requests==2.32.4",
  # ]
  # ///

• Python’s official style guide PEP 8 recommends specific conventions for import statement ordering, which can significantly improve readability. Following these conventions is standard practice, and modern tools like Ruff can enforce them.

• Avoid local or library-specific imports

• (Optional) Minimize dependencies: rely primarily on the standard library.

Command-Line Arguments

• Use helper libraries to add command-line arguments, making scripts interactive and configurable.
• Define a clear main() function to encapsulate the core script logic triggered by the command-line interface (CLI).
• Consider using third-party libraries like Click, which provides a more intuitive and Pythonic way to create CLIs using decorators.
• Leverage argument parsing for input validation: tools like Click are useful not only for defining arguments but also for validating user input at the script boundary — for example, using click.Choice or type=int. Handling input validation here often reduces the verbose try…except blocks needed for type or value checking deep inside core logic functions, keeping the code cleaner.

Structured Data

• Choose appropriate data structures to improve data representation.
• Use enum for fixed sets of choices, states, modes, and mapping inputs; recommended for clarity and type safety over raw strings or integers for predefined choices.
• Use dataclass for flexible data records with type annotations, reduced boilerplate, and easy method addition; recommended as an excellent default for most structured data. It balances functionality, readability, and ease of use.
• Use namedtuple for simple, immutable data packets, function return values, and low-overhead named access; recommended for concise, fixed records where immutability is essential.

Improving Feedback and Robustness

• Use structured logging (the built-in logging module) instead of relying entirely on print().
• Use assert statements for internal consistency checks during development.
• Improve terminal output presentation, potentially using libraries designed for richer interfaces, such as Rich. It’s ideal for creating beautiful terminal output across different operating systems, with support for colors, tables, Markdown, progress bars, and more. (You can also use it to override the default handlers for logging and exceptions)