Write type information in the function signature and use the docstring to explain what callers cannot infer from that signature: behavior, parameter meaning, return details, side effects, and relevant exceptions. A clear summary at the top makes the function’s purpose easy to scan.
What belongs in a function docstring?
A function docstring is the first string literal in the function body. Python makes it available through the function’s __doc__ attribute. The Python 3.14.8 tutorial describes this behavior, while PEP 257 gives conventions for writing docstrings.
Start with a short summary sentence. For a multi-line docstring, leave a blank line after the summary, then add details callers need. Describe the function’s effect directly rather than repeating its name or paraphrasing its signature.
Document the parts of the public contract that are useful and not obvious from the code or signature:
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problems#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
- Parameters: Use the actual parameter names and explain their meaning. Mention defaults, optionality, or restrictions when they affect how callers use the function.
- Return value: Explain what the result represents and call out meaningful cases, such as when the function may return
None. - Side effects: Note externally visible changes, such as writing a file or modifying an object, when relevant.
- Exceptions: Document exceptions callers may reasonably need to handle, along with the conditions that raise them.
- Calling constraints: Explain important preconditions and whether keyword use is part of the public interface when that matters.
Do not add empty or irrelevant sections just to make every docstring look alike. The goal is a useful contract, not a form that every function must fill out.
How do you add type hints to a function?
Put a parameter’s annotation after its name and a colon. Put the return annotation after -> and before the colon that ends the definition. For example:
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
def load_text(path: str, *, encoding: str = "utf-8") -> str:
"""Read a text file and return its contents.
Args:
path: Filesystem path to the input file.
encoding: Text encoding used to decode the file.
Returns:
The decoded file contents.
Raises:
OSError: If the file cannot be opened or read.
UnicodeError: If the input cannot be decoded with the selected encoding.
"""Here, path and encoding are annotated as strings, and the function’s return is annotated as a string. The * makes encoding keyword-only, so callers must pass it by name if they override its default. The docstring explains what the two arguments mean, what the returned text represents, and which read failures may be raised—details the annotations alone do not express.
Annotations are optional metadata stored on the function; they do not change the function’s behavior in the model described by the Python tutorial. Use them to communicate the intended types in the signature, and use prose for semantics that types cannot capture.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Which docstring style should you use?
PEP 257 recommends high-level conventions for docstrings, but it does not require a particular markup syntax for sections such as arguments, returns, or exceptions. The example above uses an Args/Returns/Raises layout; it is illustrative, not a PEP 257 mandate.
Common choices include Google-style, NumPy-style, reStructuredText, or a project-specific convention. Choose based on how the documentation will be read and maintained:
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
- Is the source readable and easy for contributors to edit?
- Can the project’s documentation tools render the chosen format correctly?
- Does it make arguments, returns, and exceptions easy to scan?
- Does it match the existing codebase’s style?
PEP 287 proposed reStructuredText as a structured plaintext format, but that does not mean every Python project uses it. Consistency with the project’s conventions and tooling is more useful than switching formats in isolation.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Do Python type hints check types at runtime?
No. Type hints do not automatically validate arguments or return values when a function runs. They are primarily metadata for static analysis and related tools. The Python 3.14.8 typing reference identifies type checkers, IDEs, and linters as consumers of hints.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
If runtime validation is required, it must come from application logic or a separate runtime-validation tool; adding an annotation by itself does not reject an unexpected value. Likewise, a type hint describes an intended contract, but it does not replace documentation of a function’s behavior or error conditions.
How should you choose type syntax?
Use annotation syntax that your project’s supported Python versions and type-checking tools understand. Newer syntax is not automatically suitable for code that must run on older interpreters. The typing reference for Python 3.14.8 is version-specific; check the documentation for the interpreter version you support and the tools your project uses.
For example, that reference says AnyStr has been deprecated since Python 3.13. It is slated for removal from typing.__all__ in Python 3.16 and from typing in Python 3.18. For the constrained type-variable use case covered by the reference, prefer the newer type-parameter syntax, provided it fits the project’s supported versions.
Quick Recap
A practical checklist
- Begin the docstring with a concise, capitalized sentence ending in a period.
- For a longer docstring, put a blank line after the summary.
- Use annotations for parameter and return types where practical.
- Explain argument meaning, return behavior, side effects, relevant exceptions, and caller constraints that the signature does not show.
- Use the real parameter identifiers in documentation.
- Follow one section style that works with the project’s documentation tools and existing code.
- Check annotation syntax against supported Python versions rather than assuming the newest syntax is universal.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
