Credentials Management

Typical usage

The most common way to input credentials into cartoframes is through the set_default_credentials method, as below. Replace {your_user_name} with your CARTO username and {your_api_key} with your API key, which you can find at https://{your_user_name}.carto.com/your_apps.

from cartoframes.auth import set_default_credentials

set_default_credentials(
    username='{your_user_name}',
    api_key='{your_api_key}'
)

When the data we’re going to use is public, we don’t need the api_key parameter, it’s automatically set to default_public:

from cartoframes.auth import set_default_credentials

set_default_credentials('your_user_name')

You can also set your credentials using the base_url parameter:

from cartoframes.auth import set_default_credentials

set_default_credentials(
    base_url='https://{your_user_name}.carto.com',
    api_key='{your_api_key}'
)

The Credentials class

Credentials management for cartoframes usage.

class cartoframes.auth.credentials.Credentials(username=None, api_key='default_public', base_url=None, session=None)

Credentials class for managing and storing user CARTO credentials. The arguments are listed in order of precedence: Credentials instances are first, key and base_url/username are taken next, and config_file (if given) is taken last. If no arguments are passed, then there will be an attempt to retrieve credentials from a previously saved session. One of the above scenarios needs to be met to successfully instantiate a Credentials object.

Parameters:
  • api_key (str, optional) – API key of user’s CARTO account
  • username (str, optional) – Username of CARTO account
  • base_url (str, optional) – Base URL used for API calls. This is usually of the form https://eschbacher.carto.com/ for user eschbacher. On premises installations (and others) have a different URL pattern.
  • session (requests.Session, optional) – requests session. See requests documentation for more information.

Example

from cartoframes.auth import Credentials
credentials = Credentials(username='eschbacher', api_key='abcdefg')
api_key

Credentials api_key

base_url

Credentials base_url

delete(config_file=None)

Deletes the credentials file specified in config_file. If no file is specified, it deletes the default user credential file.

Parameters:config_file (str) – Path to configuration file. Defaults to delete the user default location if None.

Tip

To see if there is a default user credential file stored, do the following:

>>> credentials = Credentials.from_file()
>>> print(credentials)
Credentials(username='eschbacher', api_key='abcdefg',
    base_url='https://eschbacher.carto.com/')
classmethod from_credentials(credentials)

Retrives credentials from another Credentials object

classmethod from_file(config_file=None, session=None)

Retrives credentials from a file. Defaults to the user config directory

save(config_file=None)

Saves current user credentials to user directory.

Parameters:config_loc (str, optional) – Location where credentials are to be stored. If no argument is provided, it will be send to the default location.

Example

from cartoframes import Credentials
credentials = Credentials(username='eschbacher', api_key='abcdefg')
credentials.save()  # save to default location
from cartoframes import Credentials
credentials = Credentials(username='eschbacher', api_key='abcdefg')
credentials.save('path/to/credentials/file')
session

Credentials session

username

Credentials username