Usage¶

Info

Note: this content may be a candidate for placing the developers.thegreenwebfoundation.org website. If we do this, we’d replace this page with a short para and link to it there.

Using the carbon.txt validator in python¶

Validating carbon.txt files from python¶

You can use the carbon.txt validator in python by importing and instantiating the CarbonTxtValidator class:

from carbon_txt.validators import CarbonTxtValidator

validator = CarbonTxtValidator()

This validator object can be used to validate a given domain, URL, or the contents of a carbon.txt file as a string. Each of these methods returns a ValidationResult object, which exposes logs, any exceptions encountered, an optional result containing the parsed CarbonTxtFile, and an optional url of the parsed document (if a domain or URL was validated).

Find and parse a carbon.txt file for a given domain¶

A key idea behind carbon.txt is that it you shouldn’t need to know where a carbon.txt file is on a domain to access it - there should be conventions to follow to find the file in a series of predictable places. We can perform this lookup and validate the found file, using the validate_domain method:

validator.validate_domain("carbontxt.org")
#=> ValidationResult

Parse a carbon.txt file available at a specific URL¶

We can also specify the full URL to a given carbon.txt file for validation:

validator.validate_url("https://thegreenwebfoundation.org/carbon.txt")
#=> ValidationResult

Parse a TOML string as a carbon.txt file¶

Finally, we can specify the contents of a carbon.txt file as a string, and validate that:

contents = """
version = "0.4"
last_updated = "2025-01-01"

[org]
disclosures = [
    { doc_type='web-page', url='https://example.com/sustainability-policy' },
]
"""

validator.validate_contents(contents)
#=> ValidationResult

Building carbon.txt files from python¶

We can also create carbon.txt files programatically, using the build_carbontxt_file helper function:

from carbon_txt import build_carbontxt_file

data = {
    "org": {
        "disclosures": [{"url": "https://www.example.com", "doc_type": "web-page"}]
    },
    "upstream": {
        "services": [
            {"domain": "example.com", "service_type": "virtual-private-servers"}
        ]
    },
}

build_carbontxt_file(data)
#=> CarbonTxtFile

This method will automatically validate the contents of the carbon.txt file and raise a pydantic.ValidationError if any of the data is invalid. By default, it validates against the lastest version of the carbon.txt syntax, but will use the version key of the dictionary to select the correct syntax version to validate against.

If you do not specify a last_updated property, the current date will be specified by default. If you wish to omit this, you can provide an explicit None value as the last_updated date.

Generating a carbon.txt file in TOML format¶

Any CarbonTxtFile object can be serialized as TOML, either by calling its to_toml method, which returns a TOML formatted string, or its save_toml method to save it to a given path:

from carbon_txt import build_carbontxt_file

data = {
    "org": {
        "disclosures": [{"url": "https://www.example.com", "doc_type": "web-page"}]
    },
    "upstream": {
        "services": [
            {"domain": "example.com", "service_type": "virtual-private-servers"}
        ]
    },
}

file = build_carbontxt_file(data)

file.to_toml()
#=> string with contents of TOML file

file.save_toml("/tmp/carbon.txt")
#=> saves the TOML file to the given path

Both these methods take an optional header_comment keyword argument, which will prepend a comment in the generated TOML. This is useful if you want to add a note specifying which domain the carbon.txt has been generated for, for instance:

file.save_toml("/tmp/carbon.txt", header_comment="This carbon.txt file was generated automatically for the domain example.com")

Using the carbon.txt validator on the commandline¶

The carbon.txt validator is designed to work both as a command line tool, and as a HTTP server. Once installed, run the carbon-txt binary by itself to see the commands available:

carbon-txt

You should see output like below:

Usage: carbon-txt [OPTIONS] COMMAND [ARGS]...

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --install-completion  Install completion for the current shell.                                          │
│ --show-completion     Show completion for the current shell, to copy it or customize the installation.   │
│ --help                Show this message and exit.                                                        │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────╮
│ schema     Generate a JSON Schema representation of a carbon.txt file for validation                     │
│ serve      Run the carbon.txt validator web server                                                       │
│ validate   Validate carbon.txt files, either online, or locally.                                         │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Validating files on the command line¶

Find and parse a carbon.txt file for a given domain:¶

This is inspired by the .well-known URI convention, as well as other DNS based ways to discover relevant files for a given domain.

carbon-txt validate domain some-domain.com

Parse a remote carbon.txt file available at a specific URL¶

When testing out a file it’s useful to be able to specify where to try downloading a file from. This is useful for troubleshooting, or otherwise testing out lookups

carbon-txt validate file https://somedomain.com/path-to-carbon.txt

Parse a local carbon.txt file¶

You can read a file on your local file system, to avoid needing to upload the file somewhere before trying to read, or when testing out data pipelines.

carbon-txt validate file ./path-to-file.txt

pipe the contents of a file into the file validation command as part of a pipeline¶

The carbon.txt validator tries to follow the Command Line Interface Guidelines on clig.dev, on making it possible to build composable pipelines.

You can pipe a file into the carbon.txt validator to parse it:

cat ./path-to-file.com | carbon-txt validate file

Using the carbon.txt validator as a server¶

Finally, almost all of the functions of the carbon.txt validator are available over an HTTP API too. Run carbon-txt serve to start an API server, with OpenAPI compliant documentation of each endpoint:

carbon-txt serve