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”Tag: python
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.
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
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.
openapi-SQLAlchemy Now Supports $ref for Columns
A new version of openapi-SQLAlchemy has been release which adds support for $ref for columns. The package now supports openapi schemas such as the following:
components:
schemas:
Id:
type: integer
description: Unique identifier for the employee.
example: 0
Employee:
description: Person that works for a company.
type: object
properties:
id:
$ref: "#/components/schemas/Id"
name:
type: string
description: The name of the employee.
example: David Andersson.
If you are interested in how this was accomplished with decorators and recursive programming, the following article describes the implementation: Python Recursive Decorators.
Python Recursive Decorators
In Python decorators are a useful tool for changing the behaviour of functions without modifying the original function. For a recent release of openapi-SQLAlchemy, which added support for references among table columns, I used decorators to de-reference columns. I needed a way of supporting cases where a reference to a column was just a reference to another column. The solution was to essentially keep applying the decorator until the column was actually found.
What is a Column Reference?
If you are not familiar with openapi specifications, a simple schema for an object might be the following:
components:
schemas:
Employee:
description: Person that works for a company.
type: object
properties:
id:
type: integer
description: Unique identifier for the employee.
example: 0
name:
type: string
description: The name of the employee.
example: David Andersson.
To be able to re-use the definition of the id property for another schema, you can do the following:
components:
schemas:
Id:
type: integer
description: Unique identifier for the employee.
example: 0
Employee:
description: Person that works for a company.
type: object
properties:
id:
$ref: "#/components/schemas/Id"
name:
type: string
description: The name of the employee.
example: David Andersson.
In this case, the id property just references the Id schema. This could be done for other property definitions where the same schema applies to reduce duplicate schema definitions.
The Simple Case
The openapi-SQLAlchemy package allows you to map openapi schemas to SQLAlchemy models where an object becomes a table and a property becomes a column. The architecture of the package is broken into a factory for tables which then calls a column factory for each property of an object. The problem I had to solve was that ,when a reference is encountered, the column factory gets called with the following dictionary as the schema for the column (for the id column in this case):
{"$ref": "#/components/schemas/Id"}
instead of the schema for the column. Apart from doing some basic checks, what needs to happen is that the schema of Id needs to be found and the column factory be called with that schema instead of the reference. A perfect case for a decorator! The following is the code (minus some input checks):
_REF_PATTER = re.compile(r"^#\/components\/schemas\/(\w+)$")
def resolve_ref(func):
"""Resolve $ref schemas."""
def inner(schema, schemas, **kwargs):
"""Replace function."""
# Checking for $ref
ref = schema.get("$ref")
if ref is None:
return func(schema=schema, **kwargs)
# Retrieving new schema
match = _REF_PATTER.match(ref)
schema_name = match.group(1)
ref_schema = schemas.get(schema_name)
return func(schema=ref_schema, **kwargs)
return inner
The first step is to check if the schema is a reference schema and call the column factory if not (lines 3-4). If it is a reference, then the referenced schema needs to be retrieved (lines 14-16) and the factory called with the referenced schema instead (line 18).
The Recursive Case
The problem with the simple decorator is that the following openapi specification is valid:
components:
schemas:
Id:
$ref: "#/components/schemas/RefId"
RefId:
type: integer
description: Unique identifier for the employee.
example: 0
Employee:
description: Person that works for a company.
type: object
x-tablename: employee
properties:
id:
$ref: "#/components/schemas/Id"
name:
type: string
description: The name of the employee.
example: David Andersson.
Noe that the Id schema just references the RefId schema. When this schema is used, the column factory would now be called with:
{"$ref": "#/components/schemas/RefId"}
That looks a lot like the original problem! The solution is that the decorator needs to be applied again. This also looks like a case for recursive programming. In recursive programming, you have the base case and the recursive case. The base case sounds a lot like the code that checks for whether the schema is a reference (lines 3-4 above). The recursive case needs to take a step towards the base case and apply the function again. In this case this is done by resolving one reference and then calling the decorator again. This means that on line 18 above we need to somehow apply the decorator again. The solution is actually quite simple, the code needs to be changed to the following:
_REF_PATTER = re.compile(r"^#\/components\/schemas\/(\w+)$")
def resolve_ref(func):
"""Resolve $ref schemas."""
def inner(schema, schemas, **kwargs):
"""Replace function."""
# Checking for $ref
ref = schema.get("$ref")
if ref is None:
return func(schema=schema, **kwargs)
# Retrieving new schema
match = _REF_PATTER.match(ref)
schema_name = match.group(1)
ref_schema = schemas.get(schema_name)
return inner(schema=ref_schema, schemas=schemas, **kwargs)
return inner
The change is that inner is called instead of the original function func. We then also need to pass in all the required arguments for inner, which in this case, means passing through the schemas which func does not need.
Conclusion
Recursive decorators combine the ideas behind decorators and recursive programming. If the problem a decorator solves can be broken into steps where, after each step, the decorator might need to be applied again, you might have a case for a recursive decorator. The decorator must then implement a base case where the decorator is not applied again and a recursive case where one step is taken towards the base case and the decorator is applied again.
openapi-SQLAlchemy Update
The first alpha version of openapi-SQLAlchemy has been released! It is basically what I wrote about in the post on Reducing API Code Duplication. The project is available on PyPI here: openapi-SQLAlchemy. To read more documentation and about how to use the project you can visit the GitHub repository.
Reducing API Code Duplication
One of the basic principles of good software engineering is the DRY principle – Don’t Repeat Yourself. It means that information should only exist in one place and should not be repeated elsewhere. This leads to code that is easier to maintain since any change only has to be made once, among a range of other benefits.
Practicing the principle is harder than stating it. For example, in the case of an API that is supported by a database, chances are there are overlaps between the database and API schema.
In my experience, there usually is significant overlap between the schema that is defined in the database and the schema that is returned by the linked API. Changes to the database schema might accidently not be properly propagate to the API schema or the API interface documentation might not get updated.
A popular tool for exposing a database schema to a Python application is the SQLAlchemy library. This is usually achieved by defining a models.py file with classes that map to tables in the database. For one of the API endpoints you might retrieve some of these objects from the database, apply some business logic to them and then return them through the API interface.
To communicate to your users how to interact with your API, you might write an openapi specification. You could even go further and use tools like connexion to map endpoints to Python functions for fulfilment. One part of that openapi specification is to define the returned schema of each endpoint.
To get closer to fulfilling the DRY principle you might wish that there was some way to connect the SQLAlchemy models and openapi schema so that you only have to define the schema in one place. To fulfil that wish I started an open source package called openapi-SQLAlchemy.
The aim of the package is to accept an openapi specification and simplify creating the SQLAlchemy models file. The aim for the MVP is the following. Given an openapi specification, when it is read into a python dictionary and passed to the module, a model factory is returned. That model factory can be called with the name of a schema which returns a class that is a valid SQLAlchemy model. For example:
# example-spec.yml
openapi: "3.0.0"
info:
title: Test Schema
description: API to illustrate openapi-SQLALchemy MVP.
version: "0.1"
paths:
/employee:
get:
summary: Used to retrieve all employees.
responses:
200:
description: Return all employees from the database.
content:
application/json:
schema:
type: array
items:
"$ref": "#/components/schemas/Employee"
components:
schemas:
Employee:
description: Person that works for a company.
type: object
properties:
id:
type: integer
description: Unique identifier for the employee.
example: 0
name:
type: string
description: The name of the employee.
example: David Andersson.
division:
type: string
description: The part of the company the employee works in.
example: Engineering
salary:
type: number
description: The amount of money the employee is paid.
example: 1000000.00
required:
- id
- name
- division
Normally the following models.py file would be required.
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy import Column, Integer, String, Float
Base = declarative_base()
class Employee(Base):
"""
Person that works for a company.
Attrs:
id: Unique identifier for the employee.
name: The name of the employee.
division: The part of the company the employee works in.
salary: The amount of money the employee is paid.
"""
__tablename__ = "employee"
id = Column(Integer, primary_key=True, autoincrement=True)
name = Column(String, index=True, nullable=False)
division = Column(String, index=True, nullable=False)
salary = Column(Float, nullable=False)
As you can see there is a lot of duplicate information. The aim is to instead pass the specification to openapi-SQLAlchemy and reduce the models.py file to the following:
from yaml import loads
from sqlalchemy.ext.declarative import declarative_base
from openapi_sqlalchemy import ModelFactory
Base = declarative_base()
with open("example-spec.yml") as spec_file:
SPEC = yaml.load(spec_file)
model_factory = ModelFactory(base=Base, spec=SPEC)
Employee = model_factory(name="Employee")
There is significantly less duplicate information across the specification and models file. The name of the object (Employee) is repeated a few times, although this can be viewed as a reference which means that it is acceptable.
Whilst things like whether a column is nullable can be derived from the required property of the object, there are some additional pieces of information that have to be included in the specification file. For example, not every schema must be a table. Also, the primary key, auto increment and index column modifications are not currently recorded in the specification. The final Employee schema might look like the following.
Employee:
description: Person that works for a company.
type: object
x-tablename: employee
properties:
id:
type: integer
description: Unique identifier for the employee.
example: 0
x-primary-key: true
x-autoincrement: true
name:
type: string
description: The name of the employee.
example: David Andersson.
x-index: true
division:
type: string
description: The part of the company the employee works in.
example: Engineering
x-index: true
salary:
type: number
description: The amount of money the employee is paid.
example: 1000000.00
required:
- id
- name
- division
There are more column modifiers that would need to be supported, such as the unique constraint. There are also more column types, such as foreign keys, and there is also inheritance and references that will need to be supported. All of these need to be supported whilst also ensuring that the specification remains valid.
This problem does not seem to be difficult to achieve in Python. There are also some opportunities to use some Python tricks to reduce the amount of code that needs to be written. As I develop this package I expect to write updates on progress and also write articles on some of the Python tricks.
Testing the Testing Guard Decorator in Python
Testing functions in Python that have a decorator applied to them is not ideal as the tests have to be written to take into account the decorator. The testing guard decorator can help remove the problem by selectively running the function with or without the decorator by detecting the environment in which it is run. When you make the decorator a part of your project you might like to write tests for the testing guard decorator itself.
Testing Guard Decorator
As a reminder, the following is the decorator code for the testing guard.
# testing_guard.py
"""Demonstrates a guard decorator."""
import os
def testing_guard(decorator_func):
"""
Decorator that only applies another decorator if the appropriate
environment variable is not set.
Args:
decorator_func: The function that applies the decorator.
Returns:
Function that dynamically decides whether to apply the decorator based
on the environment.
"""
def replacement(original_func):
"""
Function that is used as the decorator function instead of the
decorator function.
Args:
original_func: The function being decorated.
Returns:
Function that dynamically picks between the original and
decorated function depending on the environment.
"""
# Creating decorated function
decorated_func = decorator_func(original_func)
def apply_guard(*args, **kwargs):
"""
Dynamically picks between decorated and original function based on
environment.
"""
if os.getenv('TESTING') is not None:
# Use original function
return original_func(*args, **kwargs)
# Use decorated function
return decorated_func(*args, **kwargs)
return apply_guard
return replacement
The key pieces of functionality are on lines 39-43. Line 39 is the check for whether the function is being executed in the testing environment. If it is, the original function is called without the decorator on line 41. If it isn’t, then the decorated function is called on line 43. The key reason that the decorator works is that it gets access to both the decorator and original function and that it gets to run code every time the decorated function is run.
Testing the Testing Guard Decorator
There are 2 scenarios to test. The first is that the decorator is executed in the test environment, and the second is when it is executed in the non-test environment. In both cases we care about both that the correct function is called with the correct arguments (and that the other function is not called) and that the return value from the correct function is returned.
Let’s first define 2 fixtures that will help during testing. We will repeatedly need some generic *args and **kwargs and the particular value we choose for either doesn’t add anything to help understand the tests themselves so it is better to hide that detail in a fixture.
@pytest.fixture(scope='session')
def args():
"""Generates function *args"""
return ('arg1', 'arg2')
@pytest.fixture(scope='session')
def kwargs():
"""Generates function **kwargs"""
return {'kwargs1': 'kwarg1', 'kwarg2': 'kwarg2'}
Test Environment
When the decorator is executed in the test environment, it should call the original function and return the return value of the original function. It should not call the decorator return value. To focus the tests, let’s split those into three separate tests.
The first test just checks that the decorator return value is not called:
def test_testing_guard_set_decorated_call(monkeypatch):
"""
GIVEN TESTING environment variable is set and mock decorator
WHEN decorator is applied to a function after decorating it with the
testing guard and calling the decorated function
THEN decorator return value is not called.
"""
# Setting TESTING environment variable
monkeypatch.setenv('TESTING', '')
# Defining mock decorator
mock_decorator = mock.MagicMock()
# Decorating with testing guard and calling
guarded_mock_decorator = testing_guard(mock_decorator)
# Applying decorator
mock_decorated_func = guarded_mock_decorator(mock.MagicMock())
# Calling function
mock_decorated_func()
# Checking decorator call
mock_decorator.return_value.assert_not_called()
To understand the test, some understanding of Python decorators is required. A decorator is another function whose return value replaces the function it is decorating. A decorator could, for example, return the print function and then the function being decorator would never be called. In most cases, however, the function being decorator is called in the body of the function the decorator returns.
On line 9 of the test the testing environment is setup. On line 11 a mock function that will serve as the decorator to which the testing guard is applied is defined. On line 14 the testing guard is applied to the mock decorator. Then a mock function is decorated with guarded mock decorator on line 16 and the decorated function is called on line 18. On line 21 it is checked that the return value of the decorator, which would usually be called instead of the original function, is not called since, in the testing environment, the original function should always be called.
The next test checks that the original function is called with the correct arguments. For this we will ned the args and kwargs fixtures.
def test_testing_guard_set_func_call(monkeypatch, args, kwargs):
"""
GIVEN TESTING environment variable is set, mock function and args and
kwargs
WHEN a decorator is applied to the function after decorating it with the
testing guard and calling the decorated function with args and kwargs
THEN function is called with args and kwargs.
"""
# Setting TESTING environment variable
monkeypatch.setenv('TESTING', '')
# Defining mock decorator
mock_func = mock.MagicMock()
# Decorating with testing guard and calling
mock_decorator = mock.MagicMock()
guarded_mock_decorator = testing_guard(mock_decorator)
# Applying decorator
mock_decorated_func = guarded_mock_decorator(mock_func)
# Calling function
mock_decorated_func(*args, **kwargs)
# Checking decorator call
mock_func.assert_called_once_with(*args, **kwargs)
This tests is very similar to the first test but, instead of keeping track of the decorator, the original function is defined on line 12. The procedure on lines 14-20 is very similar to the first test with the only difference being that the mock decorated function is called with the args and kwargs fixtures. On line 23 the original function call is checked.
The final test checks the return value of the mock decorated function call. It is much like the previous test, except that it doesn’t pass in any args nor kwargs.
def test_testing_guard_set_return(monkeypatch):
"""
GIVEN TESTING environment variable is set and mock function
WHEN a decorator is applied to the function after decorating it with the
testing guard and calling the decorated function
THEN the return value is the function return value.
"""
# Setting TESTING environment variable
monkeypatch.setenv('TESTING', '')
# Defining mock function
mock_func = mock.MagicMock()
# Decorating with testing guard and calling
mock_decorator = mock.MagicMock()
guarded_mock_decorator = testing_guard(mock_decorator)
# Applying decorator
mock_decorated_func = guarded_mock_decorator(mock_func)
# Calling function
return_value = mock_decorated_func()
# Checking decorator call
assert return_value == mock_func.return_value
Non-Test Environment
The second series of tests are outside the test environment. Since the tests for the testing guard are likely running inside the test environment, it is usually best to deactivate the testing environment as a part of the test as you may want to have the testing environment active by default during your tests.
The tests are very similar to the tests in the test environment. The difference is that now the decorator return value should be called, the original function should not be called and the return value of the decorator return value should be returned. The tests are shown below.
def test_testing_guard_not_set_decorated_call(monkeypatch, args, kwargs):
"""
GIVEN TESTING environment variable is not set, mock decorator and args and
kwargs
WHEN decorator is applied to a function after decorating it with the
testing guard and calling the decorated function with args and kwargs
THEN decorator return value is called with args and kwargs.
"""
# Removing TESTING environment variable
monkeypatch.delenv('TESTING', raising=False)
# Defining mock decorator
mock_decorator = mock.MagicMock()
# Decorating with testing guard and calling
guarded_mock_decorator = testing_guard(mock_decorator)
# Applying decorator
mock_decorated_func = guarded_mock_decorator(mock.MagicMock())
# Calling function
mock_decorated_func(*args, **kwargs)
# Checking decorator call
mock_decorator.return_value.assert_called_once_with(*args, **kwargs)
def test_testing_guard_not_set_return(monkeypatch):
"""
GIVEN TESTING environment variable is not set and mock decorator
WHEN decorator is applied to a function after decorating it with the
testing guard and calling the decorated function
THEN the return value is the decorator's return value return value.
"""
# Removing TESTING environment variable
monkeypatch.delenv('TESTING', raising=False)
# Defining mock decorator
mock_decorator = mock.MagicMock()
# Decorating with testing guard and calling
guarded_mock_decorator = testing_guard(mock_decorator)
# Applying decorator
mock_decorated_func = guarded_mock_decorator(mock.MagicMock())
# Calling function
return_value = mock_decorated_func()
# Checking decorator call
assert return_value == mock_decorator.return_value.return_value
def test_testing_guard_not_set_func_call(monkeypatch):
"""
GIVEN TESTING environment variable is not set and mock function
WHEN a decorator is applied to the function after decorating it with the
testing guard and calling the decorated function
THEN function is not called.
"""
# Removing TESTING environment variable
monkeypatch.delenv('TESTING', raising=False)
# Defining mock decorator
mock_func = mock.MagicMock()
# Decorating with testing guard and calling
mock_decorator = mock.MagicMock()
guarded_mock_decorator = testing_guard(mock_decorator)
# Applying decorator
mock_decorated_func = guarded_mock_decorator(mock_func)
# Calling function
mock_decorated_func()
# Checking decorator call
mock_func.assert_not_called()
This demonstrates how to test the testing guard. The setup and teardown of your test environment might be more complicated in which case your tests would have to reflect that.
David Andersson 