Skip to main content

An API wrapper for Atlassian Confluence

Project description

======================================
PyConfluence REST API wrapper ("Pyco")
======================================

.. image:: https://img.shields.io/pypi/v/pyconfluence.svg
:target: https://img.shields.io/pypi/v/pyconfluence

.. image:: https://img.shields.io/badge/python-2.6%2C%202.7%2C%203.3%2C%203.4%2C%203.5-orange.svg
:target: https://img.shields.io/badge/python-2.6%2C%202.7%2C%203.3%2C%203.4%2C%203.5-orange

.. image:: https://travis-ci.org/FulcrumIT/pyconfluence.svg
:target: https://travis-ci.org/FulcrumIT/pyconfluence
:alt: Travis build status

.. _Twitter: https://twitter.com/MuddyTM

.. _blog: http://muddytm.github.io/

PyConfluence is an API wrapper for Atlassian's Confluence service that is used
extensively in automated documentation here at `Fulcrum Technologies <http://www.fulcrum.net/>`__.
It is designed with convenience in mind and allows for easy interaction with the
numerous services Confluence offers.

Setup
---------------

To get going with PyConfluence (or "Pyco", because "PyConfluence" has lots of
letters in it), you're first going to want to install "pyconfluence" with pip:

pip install pyconfluence

Once that's done, you'll need to give it your credentials by setting them as
environment variables. Here's the step-by-step process:

1. Create a file named ".pyconfluence" in your home directory ("~/.pyconfluence").
2. In that file, input the following lines (with appropriate credentials):

export PYCONFLUENCE_USER=[username for Confluence account]

export PYCONFLUENCE_TOKEN=[password for Confluence account]

export PYCONFLUENCE_ORG=[organization name; found in "https://[org].atlassian.net/wiki/..." URL]

3. Save the file, then add this to ".bash_profile" in your home directory ("~/.bash_profile"):

source ~/.pyconfluence

4. Once this is done, on startup these environment variables will be loaded.

5. There is no step 5, because you're done! Woo!

How to use
---------------

Import PyConfluence in your Python script by transcribing this tremendously
difficult and complex series of keywords:

import pyconfluence

Whew! You did it. Now we can begin using Pyco (remember, that's PyConfluence).

Wait, wait; I lied. We can't yet, because there's some basic stuff about
Confluence that should be explained first as it pertains to Pyco.

What does [x] mean?
---------------

Here are some words/phrases you're going to need to be familiar with, and their
definitions:

- A **page ID** is a unique identifier (in form of a number) that is given to
each and every page. There is no known way to control what page ID a page
receives. To find this ID, go to the editing interface for that page and find
it at the end of the URL. Alternatively, use the **get_page_id()** function in
Pyco. Note: in actions.py, the variable "id" is the same as the page ID.

- A **space** is a group of pages in Confluence in essence; however for purposes
in context of Pyco, this word is the same as the **space identifier**. To find
this identifier, go to the space and look at the URL. You'll find it right
after ".../wiki/display/". Unless that gets changed. Then feel free to send me
hatemail!

- A **parent ID** is the same as a **page ID** and can be found the same way.
The key difference is that a page can only be created when given a parent to
sit under; the page whose ID is given as a parent ID will become the parent to
the newly created page. Capiche? See the function **create_page()** for more
details.

- A **page name** is...yeah, you guess it. The name for a page. In Highlander
style, *there can only be one* in any given space. You can also decide exactly
what page name you want, unlike page IDs.

- **Content** is the source **XHTML** for any given page. Let me repeat: that's
**XHTML**...*not* HTML. There are subtle differences between the two that will
often give you a headache when trying to create pages. Unfortunately there's
no easy way to look at the XHTML of a page without using the API. Try
**get_page_content()** and learn some stuff!

PyConfluence functions
---------------

Now that you know all of those terms and have memorized all their definitions
word-for-word, you can begin using Pyco without breaking a sweat. Although one
would wonder why you were sweating in the first place.

Below I will list the current functions for PyConfluence. I'll be updating this
list as long as the script itself is being updated. For more information, check
out **pyconfluence/actions.py**.

- **create_page(name, parent_id, space, content)**:
Create a page in Confluence.

- **delete_page(id)**:
Delete a page from Confluence.

- **delete_page_full(id)**:
Delete a page from Confluence, along with its children.

- **get_page_full(id)**:
Return JSON containing information about page.

- **get_page_full_more(name, space)**:
Return content different than that from get_page_content, in JSON.

- **get_page_content(id)**:
Return XHTML content of a page.

- **get_page_name(id)**:
Return name of a page based on passed page id.

- **get_page_id(name, space)**:
Return id of a page based on passed page name and space.

- **page_exists(name, space)**:
Return True if named page currently exists in specified space.

- **get_page_children(id)**:
Return list of a page's children as JSON.

You've reached the end!
---------------

So...time for some self-promotion!

Follow me on Twitter_, and/or check out my blog_!

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
pyconfluence-1.1.3.tar.gz (6.3 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page