Python

Write an awesome doc for Python. A very nice an practical one extracted from Python official documentation.

View on GitHub

Better dev exp

Here we will learn about function annotations, docstrings, and formatting styles.

Function Annotation

def place_order(
        product_id : int,
        quantity : int,
        /,
        discount_code : str=None,
        *,
        shipping_address : str,
        expedited : bool=False) -> None:
    pass

Docstring

def place_order(
        product_id : int,
        quantity : int,
        /,
        discount_code : str=None,
        *,
        shipping_address : str,
        expedited : bool=False) -> None:
    """
    Places an order for a product.

    Arguments:
    - product_id (int): ID of the product (positional-only)
    - quantity (int): Quantity to order (positional-only)
    - discount_code (str): Optional promo code (positional-or-keyword)
    - shipping_address (str): Required keyword-only address
    - expedited (bool): Optional, keyword-only flag for fast shipping
    """
    pass

[!TIP]

You can learn how to write good docstring by going through PEP 0256, PEP 0257 and PEP 0258.

Formatting Styles

Most Important Points Extracted from PEP 8

VSCode + PEP 8

  1. Open “Extensions”, press Ctrl+Shift+x or click on its icon on the left hand side panel:

    Open extensions

  2. Search for “autopep8” and click on install button.

    Search

  3. Open “Settings” by pressing Ctrl+comma or clicking on the gear icon on the bottom left corner of VSCode:

    Open Settings

  4. Then search for “Format On Save” and check it:

    Check format on save setting in VSCode

  5. Configure autopep8 to be your default code formatter. To do that we need to open command palette by pressing Ctrl+Shift+p and type “format document with”:

    Configure formatter

  6. Press enter and autopep8 should be your default formatter.

    Check if autopep8 is your default formatter

    If not click on the “Configure Default Formatter”:

    Configure autopep8 as your default formatter

  7. And we need to configure it to not cross 79 line length define by PEP 8:

    Config autopep8 max-line-length

    You can learn how to do it step by step here.

  8. After that you can install “Pylint” too to get nice suggestions to improve your code quality.

[!CAUTION]

This extension in my experience does not do a very good job. So be sure to read the PEP 8 just in case it was messing with your code.

YouTube/Aparat