Skip to main content

A system for anchoring metadata in external files to source code

Project description

Python version Build Status


NB: This Python implementation of spor has been superseded by a Rust implementation. This version might be kept compatible with the Rust version, but don’t count on it for now.

A system for anchoring metadata in external files to source code.

spor lets you define metadata for elements of your source code. The metadata is kept in a separate file from your source code, meaning that you don’t need to clutter your source file with extra information encoded into comments. To accomplish this while dealing with the fact that source code changes over time, spor uses various “anchoring” techniques to keep the metadata in sync with the source code (or let you know when they become unmanageably out of sync).


Before you can use spor to anchor metadata to files, you need to initialize a repository with the init command:

$ spor init

This is very similar in spirit to git init. It creates a new directory in your current directory called .spor, and this is where spor will keep the information it needs.

Now you can create anchors. Suppose you’ve got a file,, like this:


def func(x):
    return x * 2

You can anchor metadata to line 4 (the function definition) by specifying the starting offset and anchor width like this:

$ echo "{\"meta\": \"data\"}" | spor add 32 12 10

You don’t have to pipe the metadata into the add command. If you don’t, spor will pop up an editor so that you can enter the metadata there.

The 10 at the end specifies the size of the “context” around the anchored code that we use for updating anchors.

This will associate the dictionary {meta: data} with the code return x * 2. You can see this metadata by using the list command:

$ spor list => {'meta': 'data'}

The metadata can be any valid JSON. spor doesn’t look at the data at all, so it’s entirely up to you to decide what goes there.


My main motivation for this tool comes from my work on the mutation testing tool Cosmic Ray. CR users need to be able to specify sections of their source code which should not be mutated, or which should only be mutated in specific ways. Rather than having them embed these processing directives in the source code, I thought it would be cleaner and neater to let them do so with a separate metadata file.


spor needs support for the following functionality:

  1. Add/edit/delete metadata to a specific range of text in a source file

  2. Query existing metadata

  3. Automatically update metadata when possible, or report errors when not

  4. Provide facilities facilities for “updating” metadata with new anchoring data

The design needs to be sensitive to both human users (i.e. since they may need to manually work with the metadata from time to time) as well as programmatic users. I’m sure the design will evolve as we go, so I’m going to try to keep it simple and explicit at first.

Ideally spor will work on any programming language (and, really, any text document), though its initial target will be Python source code.


Spor is new and small enough that we do fun things like try out new tools. Instead of setuptools et al., we’re using poetry. So if you want to contribute to spor, the first thing you need to do is to install poetry.

To install the package, use:

poetry install


The installation command above will install all of the test dependencies as well. To run all of the tests, run tox:


To run just the pytests unit tests, run:

poetry run pytest tests/unittests

To run the radish tests, run:

poetry run radish tests/e2e/features -b tests/e2e/radish


The field of “anchoring” is not new, and there’s some existing work we need to pay attention to:

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

spor-1.1.6.tar.gz (16.1 kB view hashes)

Uploaded source

Built Distribution

spor-1.1.6-py3-none-any.whl (16.4 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page