python-style_guide

In this guide, you will learn how to style your python code to comply with our guidelines. Using what you have learnt from reading the 'Guidelines when using Python' page of the Onboarding repository, you will complete several tasks here to help you absorb the skills.

Welcome to the collaboration! 🥳

Here you will to into practice the new skills that you have learnt. We hope that this is a useful experience for you and welcome any feedback that you may have.

• Who is this for: New members to our collaboration.
• What you'll learn: How to document, style, and test python code.
• What you'll build: A repository that complies with our style requirements.
• Prerequisites: Basic knowledge of python.
• How long: This course is TBD-step-count steps long and takes less than TBD-duration to complete.

How to start this course

1. Above these instructions, right-click Use this template and open the link in a new tab.
2. In the new tab, follow the prompts to create a new repository.
   • For owner, choose your personal account or an organization to host the repository.
   • We recommend creating a public repository—private repositories will use Actions minutes.
3. After your new repository is created, wait about 20 seconds, then refresh the page. Follow the step-by-step instructions in the new repository's README.

Step 1: Adding documentation strings

Welcome to "python-style_guide"! 👋

For the first step, lets add documentation strings to each of the functions defined in hello_numbers.py. Use the onboarding webpage to help you a short summary for each functions their parameters and returns.

What is documentation string: A documentation string (docstring) is a string that describes a module, function, class, or method definition.

def bar(var1: list, var2: int, var3: str = "hi", *args, **kwargs):
    """Short summary of the code

     Several sentences providing an extended description. Refer to
     variables using back-ticks, e.g. `var`.

     Parameters
     ----------
     var1 : array_like
         Array_like means all those objects -- lists, nested lists, etc. --
         that can be converted to an array.  We can also refer to
         variables like `var1`.
     var2 : int
         The type above can either refer to an actual Python type
         (e.g. ``int``), or describe the type of the variable in more
         detail, e.g. ``(N,) ndarray`` or ``array_like``.
     var3: {'hi', 'ho'}, optional
         Choices in brackets, default first when optional.
     *args : iterable
         Other arguments.
     **kwargs : dict
         Keyword arguments.

     Returns
     -------
     describe : type
         Explanation of return value named `describe`.
     out : type
         Explanation of `out`.
    """

⌨️ Activity: Writing docstrings

1. Open a new browser tab, and work on the steps in your second tab while you read the instructions in this tab.
2. Click on the Pull requests tab.
3. Select the pull request "Start learning python styling".
4. Click the tab Files changed.
5. For the file hello_numbers.py, click on the three dots, then select Edit file.
6. Write a short docstring for the following functions:
   1. HelloWorld
   2. SqrNumber
   3. SqrtNumber
   4. main
7. Click Commit changes.
8. Return to the main page of the repository. Wait about 20 seconds then refresh this page for the next step.

Step 2: Fixing import statements

You did Adding documentation strings! 🎉

Packages and modules that are imported should always appear at the top of the file after any module comments or docstrings, but before constants. Only one package or module should be imported per line; multiple functions from a single package can be imported on one line though. Imports should be grouped in the following order:

1. Standard library imports.
2. Related third party imports.
3. Local application or library specific imports.

⌨️ Activity: Fixing import statements

1. Reopen the file hello_numbers.py.
2. Move the import statements within the file into the correct order.
3. Click Commit changes.
4. Wait about 20 seconds then refresh this page for the next step.

Step 3: Applying naming conventions

Nice work finishing Fixing import statements ✨

When naming anything, the names that are given should be descriptive and meaningful. Avoid the use of throwaway names such as "temp". The styling should also follow the convention below:

• package_name
• module_name
• ClassName
• method_name
• ExceptionName
• function_name
• CONSTANT_NAME
• var_name
• function_parameter_name
• local_var_name

⌨️ Activity: Applying naming conventions

1. Reopen the file hello_numbers.py.
2. Apply the information above to all variable and function names.
3. Click Commit changes.
4. Wait about 20 seconds then refresh this page for the next step.

Step 4: Adding type hinting to code

Nicely done Applying naming conventions! 🥳

What is type hint: A type hint, or type annotation, is a way to indicate the type that a variable expects or that a function returns.

Type hinting can help to make code easier to understand and help to avoid TypeErrors. It can also be picked up by hooks such as mypy to spot errors in code.

def another(thing: str) -> str:
    return thing

def something(self, first_var: int):
    pass

⌨️ Activity: Adding type hinting to code

1. Reopen the file hello_numbers.py.
2. Add type hints to all the variables and functions in the file.
3. Click Commit changes.
4. Wait about 20 seconds then refresh this page for the next step.

Step 5: Writing tests for the functions

Sick work Applying naming conventions! 🎆

What is test: A test is what it sounds like, a test. Tests can be written to check for any errors in the code.

The simplest type of test is an assertion, this is where we assert that something is true. An example of a test with an assertion is:

# Content of simple test
def func(x):
    return x + 1

def test_func(x):
    assert func(3) == 4

⌨️ Activity: Writing tests for the functions

1. Reopen the file tests/test_hello_numbers.py.
2. Using what you have learnt about tests, write a simple test for each function:
   1. HelloWorld
   2. SqrNumber
   3. SqrtNumber
3. Click Commit changes.
4. Wait about 20 seconds then refresh this page for the next step.

Step 6: Merge your pull request

Almost there Writing tests for the functions! ❤️

You can now merge your pull request!

⌨️ Activity: Merge your pull request

1. Click Merge pull request.
2. Delete the branch TBD-branch-name (optional).
3. Wait about 20 seconds then refresh this page for the next step.

Finish

Congratulations friend, you've completed this course!

Here's a recap of all the tasks you've accomplished in your repository:

• Wrote docstrings describing the functions.
• Fixed the placement and order of the import statements.
• Corrected the styling of the variable and function names.
• Type hinted the code.
• Created tests.

What's next?

• TBD-continue.

---

© 2022 CHIME/FRB Collaboration • Code of Conduct • CC-BY-4.0 License