Managing Teams

Creating an Instance of an Existing Team

To interact with an existing team, you’ll want to create an instance of the Team class. This can be done by using the Keybase.team function:

TEAM = KB.team("team_name")

The above code will create a Team instance connected to the team called “team_name”. (You’ll want to change “team_name” to the name of the team with which you wish to interact.)

In the same manner, you can retrieve an instance of a team’s sub-teams by using the Team.sub_team function:

SUB_TEAM = TEAM.sub_team("sub_team_name")

It is possible to access team information without assigning the output from the Keybase.team function to a variable, like so:

team_name = "team_name"
member_count = len(KB.team(team_name).members())
print(f"The '{team_name}' team has {member_count} members.")

However, if you need to interact with the team more than once, it is best to store the Team instance in a variable, as in the first example. Each time you instantiate a Team, there will be a slight delay as the script communicates with the Keybase app, so it’s faster to store the Team object in a variable rather than creating it repeatedly.

In the following tutorials, we’ll refer to the TEAM variable when showing how to interact with Team objects.

Creating a New Team

To create a new Keybase team, simply use the Keybase.create_team function:

TEAM = KB.create_team("team_name")

The Keybase.create_team function will return a new Team instance, or will raise a KeybaseException if the team instance could not be created. Once a new team is created, its name is added to the Keybase.teams list.

Keep in mind, team names can only be up to 16 characters long.

To create sub-teams, use the Team.create_sub_team function:

>>> SUB_TEAM = TEAM.create_sub_team("sub_team_name")
>>> print(SUB_TEAM.name)
team_name.sub_team_name

The name of the resulting sub-team will be parent_team_name.sub_team_name. If the sub-team could not be created, a TeamException is raised. Note: PyKBLib does not automatically add the active user to the new sub-team.

Renaming Sub-Teams

If you wish to re-name a sub-team, you can use the Team.rename function:

>>> SUB_TEAM.rename("new_name")
>>> print(SUB_TEAM.name)
team_name.new_name

While root-level teams cannot be renamed, sub-teams can be renamed as often as you’d like.

Deleting Teams

In order to delete a team, you must first be that team’s owner.

There are two ways to delete a team in PyKBLib. You can either use the Keybase.delete_team function to delete a team by name, or you can delete a team from its instance by using the Team.delete function. For example:

# Delete team_one by name.
KB.delete_team("team_one")

# Create an instance of team_two and delete it.
TEAM = KB.team("team_two")
TEAM.delete()

If you attempt to delete a team that has sub-teams, the sub-teams will be deleted first.

If the teams cannot be deleted, a KeybaseException will be raised. Note: This doesn’t necessarily mean that the function failed entirely, however. If working with a nested team structure, it’s possible that some of the sub-teams were deleted prior to the function failing.

Accessing Team Information

Most information about a team is accessible through the Team class’ attributes:

  • Team.name (str) The name of the team.
  • Team.role (str) The team role assigned to the current user.
  • Team.members_by_role (namedtuple) A namedtuple containing sets of members sorted into their respective roles:
    • Team.members_by_role.owner (set) A set of all the owners of the team.
    • Team.members_by_role.admin (set) A set of all the admins of the team.
    • Team.members_by_role.writer (set) A set of all the writers in the team.
    • Team.members_by_role.reader (set) A set of all the readers in the team.
    • Team.members_by_role.deleted (set) A set of members who have deleted their accounts.
    • Team.members_by_role.reset (set) A set of members who have reset their accounts.

You can also get a complete set of active members using the Team.members function.

If you wanted to print out a summary of this information, you could do the following:

print(f"Information for team {TEAM.name}:")
print(f"- role: {TEAM.role}")
print("- team members:")
for member in TEAM.members():
    print(f"  - {member}")
roles = TEAM.members_by_role._asdict()
for role, member_list in roles.items():
    print(f"- {role}")
    for member in member_list:
        print(f"  - {member}")

The membership and role information is populated at the creation of the Team instance. Any time the library is used to update team member information, those changes are saved as well. However, any changes made outside the script will not be automatically recorded. In order to update the team membership information, simply use the Team.update function:

# Update the team's membership and role information.
TEAM.update()

Note that this function incurs a slight delay, due to the fact that it must retrieve fresh information from Keybase.