Add a built-in function to create and activate a Branch

[jchambers2012]

pynetbox version

v7.4.1

NetBox version

v4.1.8

Feature type

New functionality

Proposed functionality

I know this is creating the niche carve out for a single plugin but this will help simplify switching or activating a branch within the module and #642 shows how the module can use branching today.

I propose adding new functions to create and activate a branch so the user using this module doesn’t have to duplicate code between scripts to create/activate and wait for a bunch to become ready/active. Below is an example of a single function that can create and validation that it’s active. However this could also be split up into separate functions so user code can do other processing while a branch is bring created and not ready for activation. Such as:

• 1 to create a branch (non-blocking)
• 1 to activate a branch (blocking or non-rdy status return)
• 1 to verify that your in a branch (true/false)

Example of what we use today pulled from a class that wrap the module with extra functionality:

def set_branch(self, branch_name, create=True):
    # Add check here for plug-in support otherwise raise exception 

    # https://github.com/netbox-community/pynetbox/issues/642#issuecomment-2350317544
    branch = self._connection.plugins.branching.branches.get(name=branch_name)
    if not branch and create:
        branch = self._connection.plugins.branching.branches.create(
            name=branch_name, status="new" #status required via api - https://github.com/netboxlabs/netbox-branching/discussions/173
        )
        i = 0
        rdy = False
        time.sleep(1)
        while not rdy and i < 10:
            try:
                branch_test = self._connection.plugins.branching.branches.get(
                    id=branch.id
                )
                if branch_test.status.value == "ready":
                    rdy = True
            except Exception as e:
                logger.debug(f"{e}")
            i += 1
            time.sleep(10)
        if not rdy:
            raise Exception("Branch not ready")
    else:
        raise Exception("Branch not found")
    #Branch is ready so set the header
    self._connection.http_session.headers["X-NetBox-Branch"] = branch.schema_id

Use case

I have several scripts that are being converted over to utilizing the branching functionality via this module and the functionality to create and verify that a branch is active and ready to receive API calls is being duplicated across code bases purposes.

External dependencies

The external dependency will be the NetBox Labs Branching Plugin, and the functionality to activate a branch can check that the plugin is installed before executing on the api or raising exception