The Python file (.py, .pyw)

The basics

What is a PY file?

Anatomy

What's inside a Python file

A Python file is a list of statements that run from top to bottom, plus definitions (functions and classes) that run when something calls them. Indentation marks where each block starts and ends. Here is a small but complete script, part by part.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""Greet people by name."""

import sys

DEFAULT_NAME = "world"


def greet(name: str = DEFAULT_NAME) -> str:
    """Return a greeting for one person."""
    return f"Hello, {name}!"


class Greeter:
    def __init__(self, names: list[str]) -> None:
        self.names = names

    def run(self) -> None:
        for name in self.names:
            print(greet(name))


def main() -> int:
    Greeter(sys.argv[1:] or [DEFAULT_NAME]).run()
    return 0


if __name__ == "__main__":
    sys.exit(main())

1. 1#!/usr/bin/env python3

   The shebang

   Only used when the file is run as a program on macOS or Linux (./greet.py): it tells the system to run it with the first python3 on the PATH. The Windows py launcher reads it too. Python itself treats it as a comment.

2. 2# -*- coding: utf-8 -*-

   An encoding declaration

   Optional, because UTF-8 has been the default since Python 3. You only need one for a file saved in another encoding, and it must be on line 1 or 2. The -*- marks are an Emacs convention; # coding: latin-1 works just as well.

3. 3"""Greet people by name."""

   The docstring

   A string as the first statement of a file, function or class is its documentation. help(), IDEs and documentation tools show it.

4. 4import sys

   An import

   Loads another module, here one from the standard library. Python looks in the script's own folder first, which is why a file of yours called random.py hides the real random module.

5. 5DEFAULT_NAME = "world"

   A constant, by convention

   Python has no real constants. An upper-case name tells other programmers not to change it.

6. 6def greet(name: str = DEFAULT_NAME) -> str:

   A function with type hints

   name: str and -> str document the types. Python doesn't enforce them at run time; checkers such as mypy and IDEs use them.

7. 7 return f"Hello, {name}!"

   Indentation is syntax

   The four spaces put this line inside the function. There are no braces: an indent opens a block and the next line at the previous indent closes it. PEP 8 asks for four spaces per level.

8. 8class Greeter:

   A class

   Bundles data (self.names) with the methods that use it. __init__ runs when you create one, as main() does below.

9. 9def main() -> int:

   A main function

   Keeping the program's top-level steps in a function, rather than loose at the bottom of the file, means importing the file doesn't run them.

10. 10if __name__ == "__main__":

    The entry-point guard

    Python sets __name__ to "__main__" for the file you run, and to the module's name when it's imported. This block therefore runs only when the file is executed directly.

11. 11sys.exit(main())

    The exit status

    Passes main()'s return value to the operating system: 0 means success, anything else failure. Shell scripts and CI jobs check it.

Under the hood

What happens when you run a Python file

How to run it

How to run a .py file on Windows, macOS and Linux

The rules

Shebangs, encodings, file names and project layout

my-project/
  pyproject.toml        name, version, dependencies, Python version
  src/
    my_package/
      __init__.py       makes the folder an importable package
      __main__.py       runs with: python -m my_package
      report.py         a module: import my_package.report
  tests/
    test_report.py
  .venv/                the virtual environment: never share or commit it

Versions

Python 2 vs Python 3, and the versions that matter for files

Related formats

Python files and their neighbours

Troubleshooting

Errors when opening or running a Python file

How to

How to open, edit and check a Python file

# macOS and Linux
python3 -m venv .venv
source .venv/bin/activate
python -m pip install requests
python script.py

# Windows (PowerShell or Command Prompt)
py -m venv .venv
.venv\Scripts\activate
python -m pip install requests
python script.py

Security

Is it safe to open or run a Python file?

Free downloads

Sample Python files to download

Free sample Python files for testing editors, linters, syntax highlighters, upload filters and size limits. All run with Python 3.10 or later and print their results, except sample-python2.py, which fails on purpose.

Loading…

What's inside sample-script.py

The file is commented: open it in a text editor and each numbered comment marks one of these parts. Run it with python3 sample-script.py (or py sample-script.py on Windows); pass a text file's name to analyse that instead.

1. Comments 1 and 2: shebang and docstring

   The #!/usr/bin/env python3 line, then a module docstring that doubles as usage instructions.

2. Comments 3 and 4: imports and constants

   Standard library imports only, so there's nothing to install, and upper-case constants including a multi-line sample text.

3. Comment 5: a dataclass

   @dataclass(frozen=True) writes __init__ and __repr__ from the type-annotated fields, and a @property computes the reading time.

4. Comments 6 and 7: functions and files

   Type hints, regular expressions and collections.Counter, and a file read with an explicit encoding="utf-8".

5. Comment 8: command-line arguments

   argparse handles an optional file name and a --top option, and generates --help for free.

6. Comments 9 and 10: errors and output

   A missing or non-UTF-8 file produces a one-line message and exit status 1 instead of a traceback. f-strings format the results, with :, and :.1f format specs.

7. Comment 11: the entry-point guard

   if __name__ == "__main__": runs main() only when the file is executed, so other code can import analyse() without side effects.

All sample Python files

• Commented sample script

  sample-script.py · 3.9 KB (3,978 bytes)

  A small command-line tool that counts words and sentences and estimates reading time, with numbered comments explaining each part. Passes Ruff's checks.

  • Checking editors, highlighters and linters on modern Python
  • Teaching the parts of a Python file
  DownloadOpen

• UTF-8 encoding test

  sample-utf8.py · 1.9 KB (1,987 bytes)

  Greetings in 12 languages plus symbols and emoji, a non-ASCII variable name, Unicode normalisation and casefold(). Prints each string's length in characters and bytes.

  • Spotting encoding bugs in editors, pipelines and consoles
  • Testing right-to-left and CJK text in code viewers
  DownloadOpen

• Windows (CRLF) line endings

  sample-crlf.py · 852 bytes

  A script with a shebang, saved with CRLF line endings. python3 sample-crlf.py works; ./sample-crlf.py on macOS or Linux fails with the python3\r error.

  • Testing line-ending conversion in Git, editors and upload pipelines
  • Reproducing the CRLF shebang error
  DownloadOpen

• UTF-8 with a byte order mark

  sample-bom.py · 779 bytes

  Starts with the bytes EF BB BF before the shebang. Python runs it; running it as ./sample-bom.py fails because the file no longer starts with #!.

  • Checking whether a tool adds, keeps or strips a BOM
  • Reproducing BOM problems with shebang lines
  DownloadOpen

• Python 2 code (deliberate syntax error)

  sample-python2.py · 628 bytes

  Python 2 syntax: a print statement, raw_input() and except ValueError, error. Clearly labelled; Python 3 stops at line 9 with Missing parentheses in call to 'print'.

  • Testing how editors, linters and CI report syntax errors
  • Recognising Python 2 code
  DownloadOpen

• 100 KB Python file

  sample-100kb.py · 100 KB (102,400 bytes)

  A table of Collatz stopping times for 1 to 21,841 and a function that checks every entry, padded with a comment to exactly 102,400 bytes.

  • Upload and size-limit tests
  • Parser, highlighter and editor performance
  DownloadOpen

Ways to test with them

• Line endings: commit sample-crlf.py to Git or pass it through your pipeline, then check its bytes. If the CRLFs became LFs, ./sample-crlf.py will start working.
• Encoding: open sample-utf8.py in your editor or viewer and run it; garbled text such as é means something read the file as Windows-1252 instead of UTF-8.
• Error reporting: python3 -m py_compile sample-python2.py must fail with line 9; use it to check that your linter, CI job or upload validator surfaces syntax errors.
• Upload limits: sample-100kb.py is exactly 102,400 bytes, for testing a limit at the boundary. Some email services and filters block .py attachments; the samples show where yours draws the line.

Free to use for testing, teaching and demos, commercially or not, with no attribution needed. A link back to this page is always appreciated.

Questions

Python files, frequently asked