IndieWeb Utils v0.2.0 is Out

Over the last month, I have been working with James Van Dyne on IndieWeb Utils, the Python library I published toward the end of last year. IndieWeb Utils aims to provide helper functions that are useful when building applications related to the IndieWeb. For instance, the library contains features like a function to send a webmention and a function to generate a reply context from a web page.

IndieWeb Utils was my first Python library and I quickly realised I had a lot to learn about the conventions associated with building a library. I also realised my knowledge of PEP 8 and automated code quality was at the early stages. James helped set up linting, type checking, and a robust CI process that made us aware of the code quality issues we would need to address. We then set out to address them, from adding type hints to fixing import layout issues.

I am excited to announce that v0.2.0 of the library is out, the biggest release since the library was first published.

There are a few themes throughout this release. First, type hints have been added. This means you should be able to work more efficiently with IndieWeb Utils in your IDE (as long as your IDE recognises type hints). This was a particularly exciting addition because type hints make the main library code easier to read, too.

Second, many new functions have been added. This library adds a range of new functions related to building an IndieAuth server, from a function to verify an authorization request to helpers that generate an authorization code for you. I plan to update my IndieAuth server to use this library extensively as it simplifies many parts of building an IndieAuth server. With these functions, you should be able to build an IndieAuth server in Python independent of frameworks in many fewer lines of code than you would if you build the server from scratch.

This release also adds a function to send and validate a webmention. These functions will make it easy to add webmention sender and receiver components to your site.

Throughout development, we have worked hard to ensure that functions are generic enough to allow their use in many different scenarios. For example, the webmention functions could both be used as part of a social reader that implements built-in webmention support or as part of a separate webmention server. The new function to get basic profile information from a h-card could be used in a sign in flow or by an IndieAuth server.

One of the biggest changes in this release is the move toward returning Pythonic objects versus arbitrary dictionaries. Initially, I used dictionaries heavily in return types because they are convenient and many IndieWeb functions use JSON in some way (which then needs to be converted to a dictionary for processing).

There were a few issues with this approach. First, sometimes JSON objects were not complete (say, if a value was not available), which made return values inconsistent. Second, you could not depend on any autocomplete or typing assistance in your IDE like you can with objects. Also, using dictionaries meant developers would need to do their own dictionary validation to check for values, something that could be avoided if a flat object was used with defined types. For all of those reasons and more, we moved to objects. Most functions now return an object (defined in the documentation) that contains the information generated by a function.

There are many more changes in this release, all documented in the project CHANGELOG file (which is also new!). Refer to the changelog if you want to learn more about the exact additions and changes made in this release.

In the last month, I have learned a lot about Python code quality. I'm glad to say that IndieWeb Utils passes the new set of test cases we have written, a type check, and a linting check that all ensure we adhere to a strict standard when writing code. The addition of the type and linting checks in our quality process meant we needed to spend quite a bit of time improving existing code but this change was worth it. The library code itself is more readable and easier to understand than it previously was.

If you're building a project related to the IndieWeb in Python, check out indieweb-utils to see if we provide any helper functions that could assist you in your work. If you see a function that is not provided that you think should be in the library, feel free to file an issue so all contributors can discuss your addition. Maybe your idea will make it into a future release.

I must end by saying thank you to James for assisting in so many ways with building indieweb-utils, from reviewing PRs to providing feedback on ideas to writing code and much more. This release greatly benefited from his efforts.

Also posted on IndieNews.

Tagged in indieweb-utils.