Remotes API

Warning

This feature is experimental and subject to breaking changes. See the Conan stability section for more information.

class RemotesAPI(conan_api)

The RemotesAPI manages the definition of remotes, contained in the “remotes.json” file in the Conan home, supporting addition, removal, update, rename, enable, disable of remotes. These operations do not contact the servers or check their existence at all. If they are not available, they will fail later when used.

The user_xxx methods perform authentication related tasks, and some of them will contact the servers to perform such authentication

  • list(pattern=None, only_enabled=True)

    Obtain a list of Remote objects matching the pattern.

    • Parameters:

      • pattern – None, single str or list of str. If it is None, all remotes will be returned (equivalent to pattern="*").

      • only_enabled – boolean, by default return only enabled remotes

      Returns:

      A list of Remote objects

  • disable(pattern)

    Disable all remotes matching pattern

    • Parameters:

      pattern – single str or list of str. If the pattern is an exact name without wildcards like “*” and no remote is found matching that exact name, it will raise an error.

      Returns:

      the list of disabled Remote objects (even if they were already disabled)

  • enable(pattern)

    Enable all remotes matching pattern.

    • Parameters:

      pattern – single str or list of str. If the pattern is an exact name without wildcards like “*” and no remote is found matching that exact name, it will raise an error.

      Returns:

      the list of enabled Remote objects (even if they were already enabled)

  • get(remote_name)

    Obtain a Remote object

    • Parameters:

      remote_name – the exact name of the remote to be returned

      Returns:

      the Remote object, or raise an Exception if the remote does not exist.

  • add(remote: Remote, force=False, index=None)

    Add a new Remote object to the existing ones

    • Parameters:

      • remote – a Remote object to be added

      • force – do not fail if the remote already exist (but default it failes)

      • index – if not defined, the new remote will be last one. Pass an integer to insert the remote in that position instead of the last one

  • remove(pattern)

    Remove the remotes matching the pattern

    • Parameters:

      pattern – single str or list of str. If the pattern is an exact name without wildcards like “*” and no remote is found matching that exact name, it will raise an error.

      Returns:

      The list of removed Remote objects

  • update(remote_name: str, url=None, secure=None, disabled=None, index=None, allowed_packages=None)

    Update an existing remote

    • Parameters:

      • remote_name – The name of the remote to update, must exist

      • url – optional url to update, if not defined it will not be updated

      • secure – optional ssl secure connection to update

      • disabled – optional disabled state

      • index – optional integer to change the order of the remote

      • allowed_packages – optional list of packages allowed from this remote

  • rename(remote_name: str, new_name: str)

    Change the name of an existing remote

    • Parameters:

      • remote_name – The previous existing name

      • new_name – The new name

  • user_login(remote: Remote, username: str, password: str)

    Perform user authentication against the given remote with the provided username and password

    • Parameters:

      • remote – a Remote object

      • username – the user login as str

      • password – password str

  • user_logout(remote: Remote)

    Logout from the given Remote

    • Parameters:

      remote – The Remote object to logout