release 0.2.3 justin murphy, the hanover insurance...

python-socialtext DocumentationRelease 0.2.3

Justin Murphy, The Hanover Insurance Group

December 29, 2011

CONTENTS

1 The socialtext Python API 31.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 API Reference 212.1 Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.2 Appliance Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.3 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.4 Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.5 Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.6 Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272.7 Uploads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312.8 Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322.9 Webhooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332.10 Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

3 Contributing 39

4 Indices and tables 41

5 Attribution 43

Python Module Index 45

i

python-socialtext Documentation, Release 0.2.3

This is a client for Socialtext’s REST API. The goal of this project is to provide an extensible library that helps youfocus on building applications that leverage the power of Socialtext instead of worrying about HTTP methods andstatus codes.

You will need a user account on a Socialtext appliance to access the API.

See Also:

For detailed information about the API, please see the Socialtext ReST Documentation

Contents:

CONTENTS 1

https://www.socialtext.net/st-rest-docs/


2 CONTENTS

CHAPTER

ONE

THE SOCIALTEXT PYTHON API

1.1 Examples

>>> from socialtext import Socialtext>>> st = Socialtext(url="https://st.example.com", username="joe", password="abc123")>>> st.pages.list(’ws-name’)[<Page: test_page_1>, <Page: test_page_2>]

>>> st.users.list()[<User: ABC123>,<User: 987>,<User: ZYX444>,<User: 789>]

>>> signal = st.signals.create("Hello world!")<Signal: 567>

>>> signal.delete()

1.2 Classes

class socialtext.Socialtext(**kwargs)Top-level object to access the Socialtext API.

Create an instance with your credentials:

>>> st = Socialtext(server_url, username, password)

Then call methods on its managers:

>>> st.signals.list()...>>> st.webhooks.list()...

pagesA PageManager - query and create Page resources

signalsA SignalManager - query and create Signal resources.

3


usersAn UserManager - query User resources

webhooksA WebhookManager - query and create Webhook resources.

workspacesA WorkspaceManager - query Workspace resources.

impersonate(username)Make API calls on behalf of the given user. Only calls to URIs in the /data/accounts or /data/workspacesroutes are permitted. The API user must have impersonator permissions in the target Account or targetWorkspace.

Example:

# set the impersonationst.impersonate("joeuser")

# clear the impersonationst.impersonate("")

Parameters username – The username of the User to impersonate.

For more information, see the reference:

1.2.1 API Reference

Accounts

List, get, and create Socialtext accounts.

See Also:

For detailed information about the Accounts URI, please see the Socialtext documentation

Classes

class socialtext.resources.accounts.AccountManager(api)Manage Account resources.

create(name)Create a new account.

Parameters name – The name of the new account.

Return type Account

get(account)Get a specific account.

Parameters account – The Account (or ID of account) to get.

Return type Account

list(expand=False, filter=’‘)Get a list of Account resources that the calling user has access to.

Parameters

4 Chapter 1. The socialtext Python API

https://www.socialtext.net/st-rest-docs/data_accounts


• expand – Get a full list of all accounts on the appliance. This requires Business Adminpermissions.

• filter – Return accounts whose name contains the filter value.

Return type list of Account

class socialtext.resources.accounts.Account(*args, **kwargs)

Appliance Configuration

Get the Socialtext appliance configuration.

See Also:

For more detailed information about the Config URI, please see the Socialtext documentation

Classes

class socialtext.resources.appliance_config.ApplianceConfigurationManager(api)Manage the Configuration resource.

get()Get the Socialtext Appliance configuration.

class socialtext.resources.appliance_config.ApplianceConfiguration(manager,info)

A resource representing the configuration of the Socialtext appliance.

get()Get the Socialtext Appliance configuration. This will refresh the current object instance.

Exceptions

Exceptions that the API might throw:

exception socialtext.exceptions.SocialtextException(code, message=None)The base exception class for all exceptions this library raises.

exception socialtext.exceptions.BadRequest(code, message=None)HTTP 400 - Bad request: you sent some malformed data.

exception socialtext.exceptions.Unauthorized(code, message=None)HTTP 401 - Unauthorized: bad credentials.

exception socialtext.exceptions.Forbidden(code, message=None)HTTP 403 - Forbidden: your credentials don’t give you access to this resource.

exception socialtext.exceptions.NotFound(code, message=None)HTTP 404 - Not found

Groups

List, get, and create Socialtext groups.

See Also:

For detailed information about the Groups URI, please see the Socialtext documentation

1.2. Classes 5

https://www.socialtext.net/st-rest-docs/index.cgi?data_config

https://www.socialtext.net/st-rest-docs/data_groups


Classes

class socialtext.resources.groups.GroupManager(api)Manage Group resources.

create(name, account=None, description=’‘, permission_set=None)Create a new native group.

Parameters

• name – The name of the group.

• account – The Account (or ID of account) the group should belong to. If None, thegroup will belong to your default account.

• description – Text describing the group.

• permission_set – Indicates whether or not the group is self_join or private. Must be oneof PERMISSION_CHOICES. Default is self_join.

get(group, show_members=False, can_update_perms=False)Get a specific Group.

Parameters

• group – The Group (or ID of a Group) to get.

• show_members – Include a list of members. Warning, this is an expensive operation.

• can_update_perms – If True, an additional attribute will be added to the resource toindicate whether or not the calling user can update the group permissions.

Return type Group

list(expand=False, filter=’‘, discoverable=None, show_members=False)Get a list of Group resources that the calling user has access to.

Parameters

• expand – Get a full list of all groups on the appliance. The calling user must be a BusinessAdmin.

• filter – Limit the list to groups to those who match the filter expression.

• discoverable – Limit the groups list to how they are discoverable by the user. Must be oneof DISCOVERABLE_CHOICES.

• show_members – Each resource will include a list of members. Warning: This is anexpensive call.

Return type list of Group

class socialtext.resources.groups.Group(*args, **kwargs)

Pages

Manage Socialtext Pages and their associated comments, backlinks, frontlinks, and tags.

See Also:

For detailed information about the Pages URI, please see the Socialtext Documentation


https://www.socialtext.net/st-rest-docs/index.cgi?data_workspaces_ws_pages


Resources

class socialtext.resources.pages.Page(*args, **kwargs)

backlink_setAn instance of PageBacklinkManager.

comment_setAn instance of PageCommentManager.

frontlink_setAn instance of PageFrontlinkManager.

revision_setAn instance of PageRevisionManager.

tag_setAn instance of PageTagManager.

delete()Delete this page.

get_html()Get the HTML of the page content.

Return type string of HTML

get_id()Get the unique ID of the page. Returns the page_id attribute, if present, otherwise it will return a slug ofthe page name.

Return type string

name_to_id()Get a slug of the page name.

Return type string

class socialtext.resources.pages.PageRevision(manager, info)

get_html()Get the HTML representation of this page revision.


get_wikitext()Get the wikitext representation of this page revision.

Return type string of wikitext

class socialtext.resources.pages.PageTag(manager, info)A representation of a tag on a Page.

delete()Remove this tag from the Page.

Managers

class socialtext.resources.pages.PageManager(api)Manage Page resources.

1.2. Classes 7


get(page, ws=None)Get a specific page.

Parameters

• page – The Page to get

• ws – The Workspace (or name of WS) the page belongs to.

Return type Page.

get_html(page, ws=None)Get the HTML representation of a specific page.

Parameters



Return type Page.

list(ws)Get a list of all pages.

Parameters ws_name – The Workspace (or name of WS) to query

Return type list of Page.

delete(page, ws=None)Delete a page in socialtext

Parameters



create(name, ws, body, tags=[], edit_summary=None, signal_edit_summary=False)Create a page in Socialtext.

Parameters

• ws – The Workspace (or name of WS) to create the page in.

• name – Something to call the page.

• body – The WikiText content of the page.

• tags – A list of strings to add as tags on the page.

• edit_summary – A message summarizing the transaction.

• signal_edit_summary – If True, then send a signal whose body is the edit summary. Thissignal is targeted at the account to which the workspace belongs.

Return type the new Page

class socialtext.resources.pages.PageBacklinkManager(api, page)Manage the pages that link to the related page. This manager is typically instantiated as an attribue on the Pageresource.

Note: All Page instances returned by this manager will be attached to the related PageManager.



list(*args, **kwargs)Get a list of pages that link to this page.

Usage:

page.backlink_set.list()[<Page: 1>, <Page:2 >...]

Return type list of Page

class socialtext.resources.pages.PageCommentManager(api, page)Manage the comments associated with a page. This manager is typically instantiated as an attribue on the Pageresource.

Note: Only create() operations are supported.

create(comment)Post a comment to the related page. This method has no return value but will raise an error if the operationfails.

Usage:

page.comment_set.create("This a *comment* using _wikitext_")

Parameters comment – The wikitext body of the comment.

class socialtext.resources.pages.PageFrontlinkManager(api, page)Manage the pages that the related page links to. This manager is typically instantiated as an attribue on thePage resource.



Usage:

page.frontlink_set.list()[<Page: 1>, <Page:2 >...]


class socialtext.resources.pages.PageRevisionManager(api, page)Manage revisions of Page. This manager is typically instantiated as an attribue on the Page resource.

get(revision)Get a specific PageRevision.

Parameters revision – The PageRevision (or ID of the page revision) to get.

Return type PageRevision

list()Get a list of all revisions for the associated Page

Return type list of PageRevision

1.2. Classes 9


class socialtext.resources.pages.PageTagManager(api, page)Manage the tags on the related page.

create(tag)Add a specific tag to a page.

Parameters tag – The tag to add to the page.

Return type PageTag

delete(tag)Delete a PageTag from a page.

Parameters tag – A PageTag (or tag string) to delete.

get(tag)Get a specific tag on a page.

Parameters tag – A PageTag (or tag string) to get

Return type PageTag

list()Get a list of tags for the page.

Return type list of PageTag

Signals

Query and create Socialtext Signals to accounts, groups, and users.

See Also:

For detailed information abou the Signals URI, please see the Socialtext Documentation

Examples

Here are some code examples illustrating the different Siganl operations:

Get You can get a Signal from the SignalManager.:

from socialtext import Socialtext

st = Socialtext(ST_URL, ST_USER, ST_PASSWORD)

signal = st.signals.get(1234) # get using an IDsignal = st.signals.get(signal) # get using a Signal instnacesignal.get() # refresh the instance

Create You can post basic Signals to your primary account or do advanced operations with attachments and cross-group postings.

Basic Just send a basic signal to your primary account:

# send a basic signalsignal = st.signals.create("Hello world!")


https://www.socialtext.net/st-rest-docs/index.cgi?data_signals


Mention a user You can include WikiText in your signals. Here is how you would mention another user:

# you can use wikitext in the signalsignal = st.signals.create("Hey, {user: [email protected]}, did you do your TPS reports?")

Reply to a signal You can reply to a signal by specifying the Signal ID or providing a Signal instance

# get the parent thread signal = st.signals.get(1234)

# reply to the thread using a Signal instance reply = st.signals.create(“Yes, I did do my TPS reports.”,in_reply_to=signal)

# reply to the thread using the Signal ID reply = st.signals.create(“Yes, I did do my TPS reports.”,in_reply_to=1234)

Send a private message To send a private message, you will need to know the recipient’s User ID or provide aUser instance:

# send a private message using the User IDprivate_msg = st.signals.create("This is a secret", recipient=1234)

# send a private message with a User instance.recipient = st.users.get("[email protected]")private_msg = st.signals.create("This is a secret". recipient=recipient)

Using attachments You will need upload the desired files first using the UploadManager:

# some files to uploadfiles = [’C:\hello_world.txt’, ’http://url/for/image.png’]

# send them to /data/uploadsuploads = [st.uploads.create(f) for f in files]

# attach them to the signalsignal = st.signals.create("I have attachments!", attachments=uploads)

Post to Accounts You can specify a list of accounts to post a Signal to:

# post to a single groupsignal = st.signals.create("Hello account!", accounts=[1])

# cross-group postingssignal = st.signals.reate("Hello multiple groups.", accounts=[1,2,3])

Post to Groups You can specify a list of groups to post a Signal to:

# post to a single groupsignal = st.signals.create("Hello group!", groups=[1])

# cross-group postingssignal = st.signals.reate("Hello multiple groups.", groups=[1,2,3])

1.2. Classes 11


Classes

class socialtext.resources.signals.SignalManager(api)Manage Signal resources.

create(body, accounts=[], all_accounts=False, annotations=[], at=None, attachments=[],groups=[], in_reply_to=None, recipient=None)

Create a signal in Socialtext.

Parameters

• body – The body of the signal.

• accounts – A list of Account (or Account ID) that the signal should be posted to.

• all_accounts – If True, the signal will be sent to all of the user’s accounts. Any values inthe accounts keyword argument will be ignored.

• annotations – A list of meta-data to apply to the signal. Each list item must be a dictio-nary with a single key to specify the annotation type and the value of that key must be adictionary to store the key/value data.

• at – A datetime object or ISO datetime string that will be used to set the time of the signalThis parameter is helpful when migrating content from another microblogging system.Only Business Administrators can create signals using this parameter.

• in_reply_to – The Signal (or ID of the signal) to reply to. If a string is provided, it willbe considered a search string. The posted signal will be in reply to the first result of thesearch.

• groups – A list of Group (or Group ID) to post the signal to.

• attachments – A list of Upload hash-IDs that represent the files to attach to the Signal.Use the UploadManager to generate the hash-IDs. The total size of all attachments cannot exceed 50MB.

• recipient – A User (or User ID or username) to send a private message to. If a recipientis specified, the accounts and groups parameters will be ignored.

Return type Signal

delete(signal)Delete a signal.

Warning: This will permanently delete the Signal from the database. Only Business Administratorscan delete signals.

Parameters signal – The Signal (or ID of the Signal) to delete

get(signal)Get a specific signal.

Parameters signal – The Signal (or ID of the Signal) to get

Return type Signal

hide(signal)Hide a signal from retrieval and searching. The signal will still be accessible through explicit requests bythe signal creator and business administrators.

Warning: A signal can not be made “unhidden”. Please use with caution.

Parameters signal – The Signal (or Signal ID or Signal Hash) to hide.



list(accounts=[], after=None, before=None, direct=None, direction=None, following=False,groups=[], hidden=False, limit=None, offset=None, order=None, q=None, sender=None)

Get a list of all signals.

Parameters

• accounts – Filter the list to include only signals visible to the list of Account (or IDs ofAccounts).

• after – Filter the list to include only signals after a certain date. Callers can pass a datetimeobject, Signal object, or an ISO string representation.

• before – Filter the list to include only signals before a certain date. Callers can pass adatetime object, Signal object, or an ISO string representation.

• direct – Expand the results list to include direct messages. The default is that no directmessages are included in the results. Must be one of DIRECT_CHOICES.

• direction – Determines the direction of the sort (ascending or descending). Must be oneof hte DIRECTION_CHOICES.

• following – If True, the list will only include Signals from people the calling user is fol-lowing.

• groups – Filter the list to include only signals visible to the list of Group (or IDs ofGroups).

• hidden – Filter the list to include only signals that have been ‘hidden’ but not yet deleted.

• limit – The maximum number of results to return.

• offset – Returns results starting at this offset from the beginning of the list.

• order – determines the sort order of the results. Must be one of the ORDER_CHOICES

• q – A query to filter on fields indexed for searching.

• sender – Filter the list to include only signals sent by the User (or ID/username of theUser).

Return type list of Signal

class socialtext.resources.signals.Signal(*args, **kwargs)

signal_idThe signal’s primary key.

bodyThe full text of the signal as an HTML string.

atString representation of the time when the signal was created

user_idThe id of the User who created the signal.

best_full_nameThe name of the person who created the signal

annotationsUser defined metadata. See the signals annotation docs.

1.2. Classes 13

https://www.socialtext.net/st-rest-docs/index.cgi?signals_annotations


account_idsA list of the ID for each account this signal was posted to.

group_idsA list of the ID for each group this signal was posted to.

in_reply_toA BasicObject representing the signal that this is a reply to. The object has the attributes “signal_id”,“uri”, and “user_id”

mentioned_usersA list of dictionaries representing the users who were mentioned in the Signal. Each dictionary containsthe keys “id”, “username”, and “best_full_name”.

delete()Delete this signal.


get_id()Get the ID that represents this signal. The signal_id attribute is required.

Return type string

get_mentioned_user_ids()Get a list of User IDs that are mentioned in the Signal.

Return type list of string User IDs

hide()Hide this Signal from retrieving or searching. It will still be accessible through explicit requests by theSignal creator and Business Administrators


is_user_mentioned(user_id)Determines if a user with the provided user_id is mentioned in this signal’s body.

Return type boolean if the user_id is mentioned

Uploads

Upload files on your local filesystem or from a public URL to the Socialtext Appliance. Files are stored in a temporarystaging area on the appliance.

Use this API to upload files so they can be attached to Signal or Page resources.

There is no Resource for this API. The UploadManager only returns a hash-ID to represent the uploaded file.

See Also:

For more detailed information about the Uploads URI, please see the Socialtext documentation

Classes

class socialtext.resources.uploads.UploadManager(api)Upload files to the Socialtext Appliance.


https://www.socialtext.net/st-rest-docs/index.cgi?data_uploads


create(filename_or_url)Upload a local or remote file to the Socialtext appliance.

Param filename_or_url: Either the path to a file on the local file system or a URL that points tothe file.

Return type An ID-hash string

Users

Query Socialtext Users

See Also:

For more detailed information about the Users URI, please see the Socialtext documentation

Classes

class socialtext.resources.users.UserManager(api)Manage User resources.

get(user, minimal=False, want_private_fields=False, verbose=False)Get a specific user

Parameters

• user – The User (or ID of the User) to get.

• minimal – If True, the minimal representation of the user will be returned.

• want_private_fields – If True, the User object will include private fields. The caller willneed Business Admin priviledges, otherwise all private field values will default to None.

• verbose – If True, the User object will include all accounts and groups to which the userbelongs. The caller will need Business Admin privileges to see the verbose information.

Return type User

list(count=None, filter=None, offset=None, order=None, want_private_fields=False)Get a list of all users

Parameters

• count – Limit the number of users returned.

• filter – A search string to filter the search. Must be a prefix match.


• order – Sort the results by the order key. Must be one of the ORDER_CHOICES.

• want_private_fields – If True, the results will include private fields. The caller will needBusiness Admin priviledges, otherwise all private field values will default to None.

Return type list of User.

class socialtext.resources.users.User(manager, info)

Note: The User attributes are complicated. We are working to document the different variations. In the meantime, please see the Socialtext User JSON Representation documentation for more information.

1.2. Classes 15

https://www.socialtext.net/st-rest-docs/index.cgi?data_users

https://www.socialtext.net/st-rest-docs/index.cgi?json_user_representation


get_id()Get the ID of this User.

Return type str

is_member_of_account(account)Returns True if the user is a member of the provided account.

Parameters account – The Account (or ID of the Account) to check

Return type bool

is_member_of_group(group)Returns True if the user is a member of the provided group.

Parameters group – The Group (or ID of the Group) to check

Return type bool

Webhooks

Query and create Socialtext Webhooks.

See Also:

For detailed information about the Webhooks URI, please see the Socialtext Documentation

Classes

class socialtext.resources.webhooks.WebhookManager(api)Manage Webhook resources.

get(webhook)Get a single webhook.

Note: Only Business Administrators can get webhook details.

Parameters webhook – The Webhook (or ID of the webhook) to get

Return type Webhook.

list()Get a list of all webhooks the current user has access to.

Return type list of Webhook.

delete(webhook)Delete a webhook.

Parameters webhook – The Webhook (or ID of the webhook) to delete.

create(webhook_class, callback_url, account_id=None, group_id=None, workspace_id=None, de-tails=None)

Create a webhook in Socialtext.

Note: This is a general method. Try using a more specific method like create_signal_webhook()or create_page_webhook()


https://www.socialtext.net/st-rest-docs/index.cgi?webhooks


Parameters

• webhook_class – A string representation of the webhook class. Ex: “signal.create”

• callback_url – The URl the webhook will POST to.

• account_id – The ST account ID this webhook will watch for actions in.

• group_id – The ST group ID this webhook will watch for actions in.

• workspace_id – The ST workspace name this webhook will watch for actions in.

• details – Webhook class sepcific details to give the webhook.

Return type Webhook

create_page_webhook(action, callback_url, account_id=None, workspace_id=None, tag=None,page_id=None)

Create a webhook that responds to page actions

Parameters

• action – The action to listen for.

• callback_url – The URL that Socialtext will send HTTP POSTs to.

• account_id – The ID of the Account to listen for Page actions in.

• workspace_id – The ID of the Workspace to listen for Page actions in.

• tag – The tag string to listen for Pages with this tag.

Patam page_id The ID of the Page to listen for actions on.

Return type Webhook

create_signal_webhook(action, callback_url, account_id=None, group_id=None, user_id=None,tag=None)

Create a webhook that responds to signal actions

Parameters

• action – The action to listen for. Currently only supports signal.create


• account_id – The ID of the Account to listen for Signals in.

• group_id – The ID of the Group to listen for Signals in.

• user_id – The ID of the User to listen for Signals to.

• tag – The tag string to listen for in Signals.

Return type Webhook

class socialtext.resources.webhooks.Webhook(manager, info)

idThe unique identifier of this webhook.

creator_idThe ID of the User that created the webhook

classThe webhook class, such as “page.tag” or “signal.create”

1.2. Classes 17


urlThe url that Socialtext will send the HTTP POST to when the webhook fires.

group_idThe id of the Group to which this webhook belongs.

detailsA BasicObject referencing the details of the webhook. Attributes that may be present are ‘user_id’ forSignal Webhooks or ‘tag’ for Page Webhooks.

account_idThe id of the Account to which this webhook belongs.

workspace_idThe id of the Workspace to which this webhook belongs.

delete()Delete this webhook.

get_id()Get the ID of this webhook. The id attribute is required.

Return type string

Workspaces

Query Socialtext Workspaces

See Also:

For detailed information about the Workspaces URI, please see the Socialtext Documentation

Classes

class socialtext.resources.workspaces.WorkspaceManager(api)Manage Workspace resources.

get(ws)Get a specific workspace.

Parameters ws – The Workspace (or name of the workspace) to get.

Return type Workspace.

list()Get a list of all workspaces.

Return type list of Workspace.

delete(ws)Delete a workspace in socialtext

Parameters ws – The Workspace (or name of the Workspace) to delete.

create(name, title, account, cascade_css=False, clone_pages_from=None, cus-tomjs_uri=’‘, customjs_name=’‘, groups=[], permission_set=None, skin_name=’‘,show_title_below_logo=False, show_welcome_message_below_logo=False)

Create a new workspace.

Parameters

• name – The unique, URL-safe name for the workspace.


https://www.socialtext.net/st-rest-docs/index.cgi?data_workspaces


• title – The title of the workspace.

• account – The Account (or Account ID) that the workspace should belong to.

• cascade_css – If True, the workspace’s CSS will cascade.

• clone_pages_from – A Workspace (or Workspace name) to clone pages from.

• customjs_uri – The URI of a custom JS script to be loaded when viewing workspacecontent.

• customjs_name – The name of the custom JS script.

• groups – A list of Group (or Group ID) to invite to the workspace.

• permission_set – The permission set of the workspace. Must be one ofPERM_CHOICES. Default is PERM_PRIVATE.

• show_title_below_logo – If True, the workspace title will be displayed below the logo.

• show_welcome_message_below_logo – If True, a welcome message will be displayedbelow the logo.

• skin_name – The name of the skin to use for the workspace.

Return type Workspace

class socialtext.resources.workspaces.Workspace(*args, **kwargs)More attributes are available if the user is a Business Administrator, however they are currently not documentedby Socialtext.

tag_setAn instance of WorkspaceTagManager

nameThe unique name of the workspace.

titleThe verbose name for the workspace.

pages_uriThe fully qualified Page collection URI

get_id()Return the ID of the workspace. Defaults to the workspace name if present, otherwise returns the primarykey (ID).

Return type string

delete()Delete the current workspace.

class socialtext.resources.workspaces.WorkspaceTagManager(api, ws)Manage tags for a page.

get(tag)Get a specific tag that is in the workspace.

Parameters tag – A WorkspaceTag (or tag string) to get

Return type WorkspaceTag

list()Get a list of tags for the workspace.

Return type list of WorkspaceTag

1.2. Classes 19

https://www.socialtext.net/st-rest-docs/index.cgi?data_workspaces_ws



delete(tag)Delete a Tag from a workspace.

Warning: This will remove the tag from ALL the pages it belongs to.

Parameters tag – A WorkspaceTag (or tag string) to delete.

create(tag)Add a specific tag to a workspace.




CHAPTER

TWO

API REFERENCE

2.1 Accounts

List, get, and create Socialtext accounts.

See Also:

For detailed information about the Accounts URI, please see the Socialtext documentation

2.1.1 Classes

class socialtext.resources.accounts.AccountManager(api)Manage Account resources.

create(name)Create a new account.

Parameters name – The name of the new account.

Return type Account

get(account)Get a specific account.

Parameters account – The Account (or ID of account) to get.

Return type Account

list(expand=False, filter=’‘)Get a list of Account resources that the calling user has access to.

Parameters

• expand – Get a full list of all accounts on the appliance. This requires Business Adminpermissions.

• filter – Return accounts whose name contains the filter value.

Return type list of Account

class socialtext.resources.accounts.Account(*args, **kwargs)

21

https://www.socialtext.net/st-rest-docs/data_accounts


2.2 Appliance Configuration

Get the Socialtext appliance configuration.

See Also:

For more detailed information about the Config URI, please see the Socialtext documentation

2.2.1 Classes

class socialtext.resources.appliance_config.ApplianceConfigurationManager(api)Manage the Configuration resource.

get()Get the Socialtext Appliance configuration.

class socialtext.resources.appliance_config.ApplianceConfiguration(manager,info)

A resource representing the configuration of the Socialtext appliance.

get()Get the Socialtext Appliance configuration. This will refresh the current object instance.

2.3 Exceptions

Exceptions that the API might throw:

exception socialtext.exceptions.SocialtextException(code, message=None)The base exception class for all exceptions this library raises.

exception socialtext.exceptions.BadRequest(code, message=None)HTTP 400 - Bad request: you sent some malformed data.

exception socialtext.exceptions.Unauthorized(code, message=None)HTTP 401 - Unauthorized: bad credentials.

exception socialtext.exceptions.Forbidden(code, message=None)HTTP 403 - Forbidden: your credentials don’t give you access to this resource.

exception socialtext.exceptions.NotFound(code, message=None)HTTP 404 - Not found

2.4 Groups

List, get, and create Socialtext groups.

See Also:

For detailed information about the Groups URI, please see the Socialtext documentation

2.4.1 Classes

class socialtext.resources.groups.GroupManager(api)Manage Group resources.

22 Chapter 2. API Reference

https://www.socialtext.net/st-rest-docs/index.cgi?data_config

https://www.socialtext.net/st-rest-docs/data_groups


create(name, account=None, description=’‘, permission_set=None)Create a new native group.

Parameters

• name – The name of the group.

• account – The Account (or ID of account) the group should belong to. If None, thegroup will belong to your default account.

• description – Text describing the group.

• permission_set – Indicates whether or not the group is self_join or private. Must be oneof PERMISSION_CHOICES. Default is self_join.

get(group, show_members=False, can_update_perms=False)Get a specific Group.

Parameters

• group – The Group (or ID of a Group) to get.

• show_members – Include a list of members. Warning, this is an expensive operation.

• can_update_perms – If True, an additional attribute will be added to the resource toindicate whether or not the calling user can update the group permissions.

Return type Group

list(expand=False, filter=’‘, discoverable=None, show_members=False)Get a list of Group resources that the calling user has access to.

Parameters

• expand – Get a full list of all groups on the appliance. The calling user must be a BusinessAdmin.

• filter – Limit the list to groups to those who match the filter expression.

• discoverable – Limit the groups list to how they are discoverable by the user. Must be oneof DISCOVERABLE_CHOICES.

• show_members – Each resource will include a list of members. Warning: This is anexpensive call.

Return type list of Group

class socialtext.resources.groups.Group(*args, **kwargs)

2.5 Pages

Manage Socialtext Pages and their associated comments, backlinks, frontlinks, and tags.

See Also:

For detailed information about the Pages URI, please see the Socialtext Documentation

2.5.1 Resources

class socialtext.resources.pages.Page(*args, **kwargs)

2.5. Pages 23

https://www.socialtext.net/st-rest-docs/index.cgi?data_workspaces_ws_pages


backlink_setAn instance of PageBacklinkManager.

comment_setAn instance of PageCommentManager.

frontlink_setAn instance of PageFrontlinkManager.

revision_setAn instance of PageRevisionManager.

tag_setAn instance of PageTagManager.

delete()Delete this page.

get_html()Get the HTML of the page content.


get_id()Get the unique ID of the page. Returns the page_id attribute, if present, otherwise it will return a slug ofthe page name.

Return type string

name_to_id()Get a slug of the page name.

Return type string

class socialtext.resources.pages.PageRevision(manager, info)

get_html()Get the HTML representation of this page revision.


get_wikitext()Get the wikitext representation of this page revision.

Return type string of wikitext

class socialtext.resources.pages.PageTag(manager, info)A representation of a tag on a Page.

delete()Remove this tag from the Page.

2.5.2 Managers

class socialtext.resources.pages.PageManager(api)Manage Page resources.

get(page, ws=None)Get a specific page.

Parameters





Return type Page.

get_html(page, ws=None)Get the HTML representation of a specific page.

Parameters



Return type Page.

list(ws)Get a list of all pages.

Parameters ws_name – The Workspace (or name of WS) to query

Return type list of Page.

delete(page, ws=None)Delete a page in socialtext

Parameters



create(name, ws, body, tags=[], edit_summary=None, signal_edit_summary=False)Create a page in Socialtext.

Parameters

• ws – The Workspace (or name of WS) to create the page in.

• name – Something to call the page.

• body – The WikiText content of the page.

• tags – A list of strings to add as tags on the page.

• edit_summary – A message summarizing the transaction.

• signal_edit_summary – If True, then send a signal whose body is the edit summary. Thissignal is targeted at the account to which the workspace belongs.

Return type the new Page

class socialtext.resources.pages.PageBacklinkManager(api, page)Manage the pages that link to the related page. This manager is typically instantiated as an attribue on the Pageresource.



Usage:

page.backlink_set.list()[<Page: 1>, <Page:2 >...]

2.5. Pages 25



class socialtext.resources.pages.PageCommentManager(api, page)Manage the comments associated with a page. This manager is typically instantiated as an attribue on the Pageresource.

Note: Only create() operations are supported.

create(comment)Post a comment to the related page. This method has no return value but will raise an error if the operationfails.

Usage:

page.comment_set.create("This a *comment* using _wikitext_")

Parameters comment – The wikitext body of the comment.

class socialtext.resources.pages.PageFrontlinkManager(api, page)Manage the pages that the related page links to. This manager is typically instantiated as an attribue on thePage resource.



Usage:

page.frontlink_set.list()[<Page: 1>, <Page:2 >...]


class socialtext.resources.pages.PageRevisionManager(api, page)Manage revisions of Page. This manager is typically instantiated as an attribue on the Page resource.

get(revision)Get a specific PageRevision.

Parameters revision – The PageRevision (or ID of the page revision) to get.

Return type PageRevision

list()Get a list of all revisions for the associated Page

Return type list of PageRevision

class socialtext.resources.pages.PageTagManager(api, page)Manage the tags on the related page.

create(tag)Add a specific tag to a page.


Return type PageTag



delete(tag)Delete a PageTag from a page.

Parameters tag – A PageTag (or tag string) to delete.

get(tag)Get a specific tag on a page.

Parameters tag – A PageTag (or tag string) to get

Return type PageTag

list()Get a list of tags for the page.

Return type list of PageTag

2.6 Signals

Query and create Socialtext Signals to accounts, groups, and users.

See Also:

For detailed information abou the Signals URI, please see the Socialtext Documentation

2.6.1 Examples

Here are some code examples illustrating the different Siganl operations:

Get

You can get a Signal from the SignalManager.:

from socialtext import Socialtext

st = Socialtext(ST_URL, ST_USER, ST_PASSWORD)

signal = st.signals.get(1234) # get using an IDsignal = st.signals.get(signal) # get using a Signal instnacesignal.get() # refresh the instance

Create

You can post basic Signals to your primary account or do advanced operations with attachments and cross-grouppostings.

Basic

Just send a basic signal to your primary account:

# send a basic signalsignal = st.signals.create("Hello world!")

2.6. Signals 27

https://www.socialtext.net/st-rest-docs/index.cgi?data_signals


Mention a user

You can include WikiText in your signals. Here is how you would mention another user:

# you can use wikitext in the signalsignal = st.signals.create("Hey, {user: [email protected]}, did you do your TPS reports?")

Reply to a signal

You can reply to a signal by specifying the Signal ID or providing a Signal instance

# get the parent thread signal = st.signals.get(1234)

# reply to the thread using a Signal instance reply = st.signals.create(“Yes, I did do my TPS reports.”,in_reply_to=signal)

# reply to the thread using the Signal ID reply = st.signals.create(“Yes, I did do my TPS reports.”,in_reply_to=1234)

Send a private message

To send a private message, you will need to know the recipient’s User ID or provide a User instance:

# send a private message using the User IDprivate_msg = st.signals.create("This is a secret", recipient=1234)

# send a private message with a User instance.recipient = st.users.get("[email protected]")private_msg = st.signals.create("This is a secret". recipient=recipient)

Using attachments

You will need upload the desired files first using the UploadManager:

# some files to uploadfiles = [’C:\hello_world.txt’, ’http://url/for/image.png’]

# send them to /data/uploadsuploads = [st.uploads.create(f) for f in files]

# attach them to the signalsignal = st.signals.create("I have attachments!", attachments=uploads)

Post to Accounts

You can specify a list of accounts to post a Signal to:

# post to a single groupsignal = st.signals.create("Hello account!", accounts=[1])

# cross-group postingssignal = st.signals.reate("Hello multiple groups.", accounts=[1,2,3])



Post to Groups

You can specify a list of groups to post a Signal to:

# post to a single groupsignal = st.signals.create("Hello group!", groups=[1])

# cross-group postingssignal = st.signals.reate("Hello multiple groups.", groups=[1,2,3])

2.6.2 Classes

class socialtext.resources.signals.SignalManager(api)Manage Signal resources.

create(body, accounts=[], all_accounts=False, annotations=[], at=None, attachments=[],groups=[], in_reply_to=None, recipient=None)

Create a signal in Socialtext.

Parameters

• body – The body of the signal.

• accounts – A list of Account (or Account ID) that the signal should be posted to.

• all_accounts – If True, the signal will be sent to all of the user’s accounts. Any values inthe accounts keyword argument will be ignored.

• annotations – A list of meta-data to apply to the signal. Each list item must be a dictio-nary with a single key to specify the annotation type and the value of that key must be adictionary to store the key/value data.

• at – A datetime object or ISO datetime string that will be used to set the time of the signalThis parameter is helpful when migrating content from another microblogging system.Only Business Administrators can create signals using this parameter.

• in_reply_to – The Signal (or ID of the signal) to reply to. If a string is provided, it willbe considered a search string. The posted signal will be in reply to the first result of thesearch.

• groups – A list of Group (or Group ID) to post the signal to.

• attachments – A list of Upload hash-IDs that represent the files to attach to the Signal.Use the UploadManager to generate the hash-IDs. The total size of all attachments cannot exceed 50MB.

• recipient – A User (or User ID or username) to send a private message to. If a recipientis specified, the accounts and groups parameters will be ignored.

Return type Signal

delete(signal)Delete a signal.


Parameters signal – The Signal (or ID of the Signal) to delete

get(signal)Get a specific signal.

2.6. Signals 29


Parameters signal – The Signal (or ID of the Signal) to get

Return type Signal

hide(signal)Hide a signal from retrieval and searching. The signal will still be accessible through explicit requests bythe signal creator and business administrators.


Parameters signal – The Signal (or Signal ID or Signal Hash) to hide.

list(accounts=[], after=None, before=None, direct=None, direction=None, following=False,groups=[], hidden=False, limit=None, offset=None, order=None, q=None, sender=None)

Get a list of all signals.

Parameters

• accounts – Filter the list to include only signals visible to the list of Account (or IDs ofAccounts).

• after – Filter the list to include only signals after a certain date. Callers can pass a datetimeobject, Signal object, or an ISO string representation.

• before – Filter the list to include only signals before a certain date. Callers can pass adatetime object, Signal object, or an ISO string representation.

• direct – Expand the results list to include direct messages. The default is that no directmessages are included in the results. Must be one of DIRECT_CHOICES.

• direction – Determines the direction of the sort (ascending or descending). Must be oneof hte DIRECTION_CHOICES.

• following – If True, the list will only include Signals from people the calling user is fol-lowing.

• groups – Filter the list to include only signals visible to the list of Group (or IDs ofGroups).

• hidden – Filter the list to include only signals that have been ‘hidden’ but not yet deleted.

• limit – The maximum number of results to return.


• order – determines the sort order of the results. Must be one of the ORDER_CHOICES

• q – A query to filter on fields indexed for searching.

• sender – Filter the list to include only signals sent by the User (or ID/username of theUser).

Return type list of Signal

class socialtext.resources.signals.Signal(*args, **kwargs)

signal_idThe signal’s primary key.

bodyThe full text of the signal as an HTML string.

atString representation of the time when the signal was created



user_idThe id of the User who created the signal.

best_full_nameThe name of the person who created the signal

annotationsUser defined metadata. See the signals annotation docs.

account_idsA list of the ID for each account this signal was posted to.

group_idsA list of the ID for each group this signal was posted to.

in_reply_toA BasicObject representing the signal that this is a reply to. The object has the attributes “signal_id”,“uri”, and “user_id”

mentioned_usersA list of dictionaries representing the users who were mentioned in the Signal. Each dictionary containsthe keys “id”, “username”, and “best_full_name”.

delete()Delete this signal.


get_id()Get the ID that represents this signal. The signal_id attribute is required.

Return type string

get_mentioned_user_ids()Get a list of User IDs that are mentioned in the Signal.

Return type list of string User IDs

hide()Hide this Signal from retrieving or searching. It will still be accessible through explicit requests by theSignal creator and Business Administrators


is_user_mentioned(user_id)Determines if a user with the provided user_id is mentioned in this signal’s body.

Return type boolean if the user_id is mentioned

2.7 Uploads

Upload files on your local filesystem or from a public URL to the Socialtext Appliance. Files are stored in a temporarystaging area on the appliance.

Use this API to upload files so they can be attached to Signal or Page resources.

2.7. Uploads 31

https://www.socialtext.net/st-rest-docs/index.cgi?signals_annotations


There is no Resource for this API. The UploadManager only returns a hash-ID to represent the uploaded file.

See Also:

For more detailed information about the Uploads URI, please see the Socialtext documentation

2.7.1 Classes

class socialtext.resources.uploads.UploadManager(api)Upload files to the Socialtext Appliance.

create(filename_or_url)Upload a local or remote file to the Socialtext appliance.

Param filename_or_url: Either the path to a file on the local file system or a URL that points tothe file.

Return type An ID-hash string

2.8 Users

Query Socialtext Users

See Also:

For more detailed information about the Users URI, please see the Socialtext documentation

2.8.1 Classes

class socialtext.resources.users.UserManager(api)Manage User resources.

get(user, minimal=False, want_private_fields=False, verbose=False)Get a specific user

Parameters

• user – The User (or ID of the User) to get.

• minimal – If True, the minimal representation of the user will be returned.

• want_private_fields – If True, the User object will include private fields. The caller willneed Business Admin priviledges, otherwise all private field values will default to None.

• verbose – If True, the User object will include all accounts and groups to which the userbelongs. The caller will need Business Admin privileges to see the verbose information.

Return type User

list(count=None, filter=None, offset=None, order=None, want_private_fields=False)Get a list of all users

Parameters

• count – Limit the number of users returned.

• filter – A search string to filter the search. Must be a prefix match.


• order – Sort the results by the order key. Must be one of the ORDER_CHOICES.


https://www.socialtext.net/st-rest-docs/index.cgi?data_uploads

https://www.socialtext.net/st-rest-docs/index.cgi?data_users


• want_private_fields – If True, the results will include private fields. The caller will needBusiness Admin priviledges, otherwise all private field values will default to None.

Return type list of User.

class socialtext.resources.users.User(manager, info)

Note: The User attributes are complicated. We are working to document the different variations. In the meantime, please see the Socialtext User JSON Representation documentation for more information.

get_id()Get the ID of this User.

Return type str

is_member_of_account(account)Returns True if the user is a member of the provided account.

Parameters account – The Account (or ID of the Account) to check

Return type bool

is_member_of_group(group)Returns True if the user is a member of the provided group.

Parameters group – The Group (or ID of the Group) to check

Return type bool

2.9 Webhooks

Query and create Socialtext Webhooks.

See Also:

For detailed information about the Webhooks URI, please see the Socialtext Documentation

2.9.1 Classes

class socialtext.resources.webhooks.WebhookManager(api)Manage Webhook resources.

get(webhook)Get a single webhook.

Note: Only Business Administrators can get webhook details.

Parameters webhook – The Webhook (or ID of the webhook) to get

Return type Webhook.

list()Get a list of all webhooks the current user has access to.

Return type list of Webhook.

2.9. Webhooks 33

https://www.socialtext.net/st-rest-docs/index.cgi?json_user_representation

https://www.socialtext.net/st-rest-docs/index.cgi?webhooks


delete(webhook)Delete a webhook.

Parameters webhook – The Webhook (or ID of the webhook) to delete.

create(webhook_class, callback_url, account_id=None, group_id=None, workspace_id=None, de-tails=None)

Create a webhook in Socialtext.

Note: This is a general method. Try using a more specific method like create_signal_webhook()or create_page_webhook()

Parameters

• webhook_class – A string representation of the webhook class. Ex: “signal.create”

• callback_url – The URl the webhook will POST to.

• account_id – The ST account ID this webhook will watch for actions in.

• group_id – The ST group ID this webhook will watch for actions in.

• workspace_id – The ST workspace name this webhook will watch for actions in.

• details – Webhook class sepcific details to give the webhook.

Return type Webhook

create_page_webhook(action, callback_url, account_id=None, workspace_id=None, tag=None,page_id=None)

Create a webhook that responds to page actions

Parameters

• action – The action to listen for.


• account_id – The ID of the Account to listen for Page actions in.

• workspace_id – The ID of the Workspace to listen for Page actions in.

• tag – The tag string to listen for Pages with this tag.

Patam page_id The ID of the Page to listen for actions on.

Return type Webhook

create_signal_webhook(action, callback_url, account_id=None, group_id=None, user_id=None,tag=None)

Create a webhook that responds to signal actions

Parameters

• action – The action to listen for. Currently only supports signal.create


• account_id – The ID of the Account to listen for Signals in.

• group_id – The ID of the Group to listen for Signals in.

• user_id – The ID of the User to listen for Signals to.

• tag – The tag string to listen for in Signals.



Return type Webhook

class socialtext.resources.webhooks.Webhook(manager, info)

idThe unique identifier of this webhook.

creator_idThe ID of the User that created the webhook

classThe webhook class, such as “page.tag” or “signal.create”

urlThe url that Socialtext will send the HTTP POST to when the webhook fires.

group_idThe id of the Group to which this webhook belongs.

detailsA BasicObject referencing the details of the webhook. Attributes that may be present are ‘user_id’ forSignal Webhooks or ‘tag’ for Page Webhooks.

account_idThe id of the Account to which this webhook belongs.

workspace_idThe id of the Workspace to which this webhook belongs.

delete()Delete this webhook.

get_id()Get the ID of this webhook. The id attribute is required.

Return type string

2.10 Workspaces

Query Socialtext Workspaces

See Also:

For detailed information about the Workspaces URI, please see the Socialtext Documentation

2.10.1 Classes

class socialtext.resources.workspaces.WorkspaceManager(api)Manage Workspace resources.

get(ws)Get a specific workspace.

Parameters ws – The Workspace (or name of the workspace) to get.

Return type Workspace.

list()Get a list of all workspaces.

2.10. Workspaces 35

https://www.socialtext.net/st-rest-docs/index.cgi?data_workspaces


Return type list of Workspace.

delete(ws)Delete a workspace in socialtext

Parameters ws – The Workspace (or name of the Workspace) to delete.

create(name, title, account, cascade_css=False, clone_pages_from=None, cus-tomjs_uri=’‘, customjs_name=’‘, groups=[], permission_set=None, skin_name=’‘,show_title_below_logo=False, show_welcome_message_below_logo=False)

Create a new workspace.

Parameters

• name – The unique, URL-safe name for the workspace.

• title – The title of the workspace.

• account – The Account (or Account ID) that the workspace should belong to.

• cascade_css – If True, the workspace’s CSS will cascade.

• clone_pages_from – A Workspace (or Workspace name) to clone pages from.

• customjs_uri – The URI of a custom JS script to be loaded when viewing workspacecontent.

• customjs_name – The name of the custom JS script.

• groups – A list of Group (or Group ID) to invite to the workspace.

• permission_set – The permission set of the workspace. Must be one ofPERM_CHOICES. Default is PERM_PRIVATE.

• show_title_below_logo – If True, the workspace title will be displayed below the logo.

• show_welcome_message_below_logo – If True, a welcome message will be displayedbelow the logo.

• skin_name – The name of the skin to use for the workspace.

Return type Workspace

class socialtext.resources.workspaces.Workspace(*args, **kwargs)More attributes are available if the user is a Business Administrator, however they are currently not documentedby Socialtext.

tag_setAn instance of WorkspaceTagManager

nameThe unique name of the workspace.

titleThe verbose name for the workspace.

pages_uriThe fully qualified Page collection URI

get_id()Return the ID of the workspace. Defaults to the workspace name if present, otherwise returns the primarykey (ID).

Return type string

delete()Delete the current workspace.





class socialtext.resources.workspaces.WorkspaceTagManager(api, ws)Manage tags for a page.

get(tag)Get a specific tag that is in the workspace.

Parameters tag – A WorkspaceTag (or tag string) to get


list()Get a list of tags for the workspace.

Return type list of WorkspaceTag

delete(tag)Delete a Tag from a workspace.

Warning: This will remove the tag from ALL the pages it belongs to.

Parameters tag – A WorkspaceTag (or tag string) to delete.

create(tag)Add a specific tag to a workspace.



2.10. Workspaces 37

CHAPTER

THREE

CONTRIBUTING

Development takes place on GitHub; please file bug reports and pull requests there.

39

https://github.com/hanover/python-socialtext


40 Chapter 3. Contributing

CHAPTER

FOUR

INDICES AND TABLES

• genindex

• modindex

• search

41


42 Chapter 4. Indices and tables

CHAPTER

FIVE

ATTRIBUTION

This foundation of this project is based on python-cloudservers by Jacob Kaplan-Moss.

Thank you to all of the developers at Socialtext and those who have made suggestions on Socialdev.

43

https://github.com/jacobian/python-cloudservers

http://jacobian.org


44 Chapter 5. Attribution

PYTHON MODULE INDEX

ssocialtext, 3socialtext.exceptions, 22

45

release 0.2.3 justin murphy, the hanover insurance...

Documents