Is This Code Worth Testing?

Many of us face this question on a daily basis. In many cases, the answer is yes. In certain cases, the answer is no or somewhere in between. It is important to weigh the benefits against the cost, and consider the extent to which code should be tested. A code coverage tool may report a line of code as covered, but that does not guarantee it has been thoroughly tested. Another consideration is the kinds of tests we write to begin with. For example, should a private function have tests? Or should it be covered by the tests of a public function that makes use of it? Should a function be covered by integration tests or end to end tests? We will explore these questions by examining several examples of code and determine whether and which types of tests are worth writing.

Continue reading “Is This Code Worth Testing?”

flake8-docstrings-complete Now Checks for Duplicate Descriptions

Version v1.1.0 of flake8-docstrings-complete has added new rules that ensure you only document each argument, raised exception and class attribute once:

  • DCO025: function/ method has one or more arguments described in the docstring multiple times.
  • DCO056: function/ method has one or more exceptions described in the docstring multiple times.
  • DCO065: class has one or more attributes described in the docstring multiple times.
Continue reading “flake8-docstrings-complete Now Checks for Duplicate Descriptions”

Navigating Mocks in Python: Strategies for Safe and Efficient Mock Usage

Do you spend a lot of time on maintaining your mocks? Has your test suite passed and your code failed to run in production? This could be a result of using mocks too aggressively or not utilising safety features provided by Python’s mock library. In this post, we will explore the benefits and potential risks of using mocks, discuss strategies for designing high-level interfaces that are safe to mock, and examine a linter tool that ensures safe mock usage. Let’s begin by examining the potential risks associated with using mocks.

Continue reading “Navigating Mocks in Python: Strategies for Safe and Efficient Mock Usage”

How ChatGPT Can Enhance Your Coding

Tired of sifting through cluttered websites to figure out that git command? In this post I try out ChatGPT, a preview release by OpenAI. Not only does it provide help with git commands, I also found it useful for various tasks such as remembering how to use Python’s functools.reduce function, enhancing documentation, creating clear docstrings, optimising functions, and even finding edge case tests. Join me in discovering how AI can boost productivity!

Continue reading “How ChatGPT Can Enhance Your Coding”

Writing Great Docstrings in Python

Have you ever tried to understand a new project by looking at the source code only to find that the code isn’t clear on its own and is lacking documentation, such as docstrings? I have had that experience a few times which slowed down being able to fix bugs and add new features and frequently also meant that the code wasn’t well structured. In this post we’ll look at best practices for documenting in code and its numerous benefits such as helping you be clear on what you actually need to code and reminding yourself and others about how the code works when you come back from an extended holiday. We will also look at a linter that checks your docstrings to make sure they are complete. Your future self will then never be frustrated about a lack of documentation in code again!

Continue reading “Writing Great Docstrings in Python”

Giving and Receiving Great Feedback through PRs

Do you struggle with PRs? Have you ever had to change code even though you disagreed with the change just to land the PR? Have you ever given feedback that would have improved the code only to get into a comment war? We’ll discuss how to give and receive feedback to extract maximum value from it and avoid all the communication problems that come with PRs. We’ll start with some thoughts about what PRs are intended to achieve and then first discuss how to give feedback that will be well received and result in improvements to the code followed by how to extract maximum value from feedback you receive without agreeing to suboptimal changes. Finally, we will look at a checklist for giving and receiving feedback you can use as you go through reviews both as an author and reviewer.

Continue reading “Giving and Receiving Great Feedback through PRs”

Writing Great Test Documentation

Have you ever needed to understand a new project and started reading the tests only to find that you have no idea what the tests are doing? Writing great test documentation as you are writing tests will improve your tests and help you and others reading the tests later. We will first look at why test documentation is important both when writing tests and for future readers and then look at a framework that helps give some structure to your test documentation. Next, we will look at a showcase of the flake8-test-docs tool that automates test documentation checks to ensure your documentation is great! Finally, we briefly discuss how this framework would apply in more advanced cases, such as when you are using fixtures or parametrising tests.

Continue reading “Writing Great Test Documentation”

Help your Users fix your Errors

Have you ever encountered an error when using a package and then gone to Google to find out how to solve the error only not to find any clear answers? Wouldn’t you have preferred to go directly to documentation that tells you exactly what went wrong and how to resolve that error? A lot of us can tell similar stories, especially when we try something new. I have also abandoned an otherwise promising package after encountering an error that wasn’t clear or when I didn’t know how to solve the error.

Continue reading “Help your Users fix your Errors”

Reduce Duplication in Pytest Parametrised Tests using the Walrus Operator

Do you find yourself having to repeat literal values (like strings and integers) in parametrised tests? I often find myself in this situation and have been looking for ways of reducing this duplication. To show an example, consider this trivial function:

def get_second_word(text: str) -> str | None:
    """Get the second word from text."""
    words = text.split()
    return words[1] if len(words) >= 2 else None
Continue reading “Reduce Duplication in Pytest Parametrised Tests using the Walrus Operator”

Inheritance for SQLAlchemy Models

In software engineering one of the key principles of object oriented software is the concept of inheritance. It can be used to increase code re-use which reduces the volume of tests and speeds up development. You can use inheritance in SQLAlchemy as described here. However, this inheritance is mainly used to describe relationships between tables and not for the purpose of re-using certain pieces of models defined elsewhere.

The openapi specification allows for inheritance using the allOf statement. This means that you could, for example, define a schema for id properties once and re-use that schema for any number of objects where you can customise things like the description that may differ object by object. You can also use allOf to combine objects, which is a powerful way of reducing duplication. You could, for example, define a base object with an id and name property that you then use repeatedly for other objects so that you don’t have to keep giving objects an id and a name.

If this feature could be brought to SQLAlchemy models, you would have a much shorter models.py files which is easier to maintain and understand. The plan for the openapi-SQLAlchemy package is to do just that. The first step has been completed with the addition of support for allOf for column definitions. If you aren’t familiar with the package, the Reducing API Code Duplication article describes the aims of the package.

To start using the column inheritance feature, read the documentation for the feature which describes it in detail and gives and example specification that makes use of it.