musicbrainzngs

The library uses Python's standard logging module. All logs are sent to a logger named musicbrainzngs. You can enable debug output for your entire application or specifically restrict musicbrainzngs to INFO level to reduce noise.

import logging
logging.basicConfig(level=logging.DEBUG)
# optionally restrict musicbrainzngs output to INFO messages
logging.getLogger("musicbrainzngs").setLevel(logging.INFO)

If you need the latest development code or wish to contribute to the project, you can clone the repository from GitHub and install it manually using setup.py.

git clone git://github.com/alastair/python-musicbrainzngs.git
python setup.py install

The easiest way to install the latest stable version of musicbrainzngs is using pip from the Python Package Index (PyPI).

pip install musicbrainzngs

If you need to submit data to MusicBrainz, you must authenticate using your MusicBrainz website credentials. Use the musicbrainzngs.auth method to set your username and password. Once called, these credentials are saved and automatically applied to all subsequent functions that require authentication.

Errors:

• If you call an authentication-required method without authenticating, a musicbrainzngs.UsageError is raised.
• If the credentials provided are incorrect (server returns 401), a musicbrainzngs.AuthenticationError is raised.

import musicbrainzngs

musicbrainzngs.auth("your_username", "your_password")

To comply with MusicBrainz webservice access rules, you must identify your application by setting a unique useragent header. Use musicbrainzngs.set_useragent to automatically format a useragent string based on your application's name, version, and contact information.

Note: If you attempt to make a request without setting a useragent first, the library will raise a musicbrainzngs.UsageError.

import musicbrainzngs

musicbrainzngs.set_useragent(
    appname="My Awesome App",
    appversion="1.0.0",
    contact="my@email.com"
)

To use the library, import musicbrainzngs. Before making requests, you must identify your application using set_useragent to comply with MusicBrainz webservice rate limiting rules. If you intend to submit data (write operations) rather than just querying, you must also authenticate using auth.

import musicbrainzngs

# Identify your application (Required by MusicBrainz)
musicbrainzngs.set_useragent("Example music app", "0.1", "http://example.com/music")

# Authenticate if submitting data
musicbrainzngs.auth("user", "password")

When testing data submission logic, you should point the library to the MusicBrainz test server instead of the production server. Use musicbrainzngs.set_hostname("test.musicbrainz.org") to switch hosts.

Example for submitting barcodes:

import musicbrainzngs

# Switch to test server
musicbrainzngs.set_hostname("test.musicbrainz.org")

# Authenticate with test credentials
musicbrainzngs.auth("test", "mb")

barcodes = {
    "174a5513-73d1-3c9d-a316-3c1c179e35f8": "5099749534728",
    "838952af-600d-3f51-84d5-941d15880400": "602517737280"
}

musicbrainzngs.submit_barcodes(barcodes)

The set_useragent method is required by MusicBrainz webservice access rules to prevent rate limiting issues. It allows the service to identify your application and contact you if necessary.

Signature: musicbrainzngs.set_useragent(name, version, contact)

musicbrainzngs.set_useragent("Example music app", "0.1", "http://example.com/music")

Before making requests, you should configure the library's environment. This includes setting your user agent (required by MusicBrainz), rate limits, and hostnames. Use the following functions to manage these settings:

• set_useragent(useragent): Sets the user agent string. This is required by MusicBrainz webservice access rules.
• set_rate_limit(rate_limit): Configures the rate limiting behavior.
• set_hostname(hostname): Sets the primary MusicBrainz hostname.
• set_caa_hostname(hostname): Sets the Cover Art Archive hostname.
• set_parser(parser): Configures the XML parser.
• set_format(format): Sets the desired response format.

If you need to connect to a different MusicBrainz server (for example, a beta or staging environment), use set_hostname.

Signature: musicbrainzngs.set_hostname(hostname)

musicbrainzngs.set_hostname("beta.musicbrainz.org")