Python bindings for SpinChimp API.¶

SpinChimp¶

class spinchimp.SpinChimp(email, apikey, aid='')[source]¶

A class representing the Spin Chimp API (http://spinchimp.com/api). All articles must be in UTF-8 encoding!

URL = 'http://api.spinchimp.com/{method}?'¶

URL for invoking the API

_get_param_value(param_name, params, def_params={'applyinstantunique': '0', 'fullcharset': '0', 'rewrite': '0', 'spintidy': '0', 'spinwithinspin': '0', 'quality': '4', 'tagprotect': '', 'protectedterms': '', 'maxspindepth': '0', 'spinwithinhtml': '0', 'posmatch': '3', 'phraseignorequality': '0'})[source]¶

Returns parameter value or use default.

_send_request(method, text, params)[source]¶

Invoke Spin Chimp API with given parameters and return its response.

Parameters:	params (dictionary) – parameters to pass along with the request
Returns:	API’s response (article)
Return type:	string

_validate(params)[source]¶

Checks every single parameter and raise error on wrong key or value.

_value_has(param, values, params)[source]¶

Raise WrongParameterVal if value of param is not in values.

_value_is_int(param, params)[source]¶

Raise WrongParameterVal if value of param is not integer.

quota_all()[source]¶

The server returns: daily limit, remaining daily limit, extended quota and bulk quota in dictionary for this account.

quota_left_total()[source]¶

The server returns remaining query times of this account.

static test_connection()[source]¶

Static method that checks server status. The server returns ‘OK’ on successful connection.

text_with_spintax(text, params=None)[source]¶

Return processed spun text with spintax.

Parameters:	text (string) – original text that needs to be changed params (dictionary) – parameters to pass along with the request
Returns:	processed text in spintax format
Return type:	string

unique_variation(text, params=None)[source]¶

Return a unique variation of the given text.

Parameters:	text (string) – original text that needs to be changed params (dictionary) – parameters to pass along with the request
Returns:	processed text
Return type:	string

unspun(text, dontincludeoriginal=0, reorderparagraphs=0)[source]¶

Generates an unspun doc from one with spintax. Optionally reorders paragraphs and removes original word.

Parameters:	text (string) – text in spintax format dontincludeoriginal (integer) – 0 (False) or 1 (True) reorderparagraphs (integer) – 0 (False) or 1 (True)
Returns:	unique text
Return type:	dictionary

word_density(text, minlength=3)[source]¶

Calculates the word densities of words and phrases in the article.

Parameters:	text (string) – original text minlength (integer) – minimum length
Returns:	words as keys in dictionary and percents as values
Return type:	dictionary

Exceptions¶

exception spinchimp.exceptions.ArticleError(msg)[source]¶

Raised when spinning article.

exception spinchimp.exceptions.AuthenticationError(msg)[source]¶

Raised when authentication error occurs.

exception spinchimp.exceptions.InternalError(msg)[source]¶

Raised when unexpected error occurs on the API server when processing a request.

exception spinchimp.exceptions.NetworkError(msg)[source]¶

Raised if there are network problems, like timeout.

exception spinchimp.exceptions.QuotaLimitError(msg)[source]¶

Raised when API quota limit is reached.

exception spinchimp.exceptions.SpinChimpError(api_error_msg)[source]¶

Base class for exceptions in Spin Chimp module.

exception spinchimp.exceptions.UnknownError(msg)[source]¶

Raised when API call results in an unrecognized error.

exception spinchimp.exceptions.WrongParameterName(name)[source]¶

Raised on unsuppported parameter name.

exception spinchimp.exceptions.WrongParameterVal(name, val)[source]¶

Raised on invalid parameter value.

Dependencies¶

A C/C++ compilation environment

On a Debian based system install the build-essential package. On OS X, install XCode and MacPorts.

Git

On a Debian based system install the git-core package. On OS X, get the latest version from http://code.google.com/p/git-osx-installer/.

Python 2.7

On a Debian based system install the python2.7-dev package. On OS X (and others) use the buildout.python to prepare a clean Python installation.

Build¶

First, you need to clone the git repository on GitHub to download the code to your local machine:

$ git clone git@github.com:niteoweb/spinchimp.git

What follows is initializing the buildout environment:

$ cd spinchimp
$ python2.7 bootstrap.py

And now you can run the buildout. This will fetch and configure tools and libs needed for developing spinchimp:

$ bin/buildout

Verify¶

Your environment should now be ready. Test that by using the py Python interpreter inside the bin directory, which has spinchimp installed in it’s path:

$ bin/py

>>> from spinchimp import SpinChimp
>>> sc = SpinChimp('api_key', 'username', 'password')
>>> sc.unique_variation('Some random text.')
u"Some random lines."

The code for spinchimp lives in src/. Make a change and re-run bin/py to see it resembled!

Moreover, you should have the following tools in the bin/ directory, ready for use:

vvv

A sintax validation tool.

sphinbuilder

A tool for testing HTML render of spinchimp‘s documentation.

longtest

A tool for testing the HTML render of the package description (part of zest.releaser).

mkrelease

A tool we use for releasing a new version (part of jarn.mkrelease).

Line length¶

All Python code in this package should be PEP8 valid. However, we don’t enforce the 80-char line length rule. It is encouraged to have your code formatted in 80-char lines, but somewhere it’s just more readable to break this rule for a few characters. Long and descriptive test method names are a good example of this.

About imports¶

1. Don’t use * to import everything from a module.
2. Don’t use commas to import multiple stuff on a single line.
3. Don’t use relative paths.

from collective.table.local import add_row
from collective.table.local import delete_rows
from collective.table.local import update_cell

instead of

from collective.table.local import *
from collective.table.local import add_row, delete_rows
from .local import update_cell

Sort imports¶

As another imports stylistic guide: Imports of code from other modules should always be alphabetically sorted with no empty lines between imports. The only exception to this rule is to keep one empty line between a group of from x import y and a group of import y imports.

from collective.table.tests.base import TableIntegrationTestCase
from plone.app.testing import login

import os

instead of

import os

from plone.app.testing import login
from collective.table.tests.base import TableIntegrationTestCase

Commit checklist¶

Before every commit you should:

• Run Unit tests.
• Run Syntax validation.
• Add an entry to Changelog (if applicable).
• Add/modify Sphinx documentation (if applicable).

Unit tests¶

Un-tested code is broken code.

For every feature you add to the codebase you must also add tests for it. Also write a test for every bug you fix to ensure it doesn’t crop up again in the future.

You run tests like this:

$ bin/test

Syntax validation¶

All Python source code should be PEP-8 valid and checked for syntax errors. Tool for checking this is vvv.

To validate your source code, run the following two commands:

$ bin/vvv src/spinchimp

Changelog¶

Feature-level changes to code are tracked inside docs/HISTORY.txt. Examples:

• added feature X
• removed Y
• fixed bug Z

Add an entry every time you add/remove a feature, fix a bug, etc.

Sphinx documentation¶

Un-documented code is broken code.

For every feature you add to the codebase you should also add documentation for it to docs/.

After adding/modifying documentation, re-build Sphinx and check how it is displayed:

$ bin/sphinxbuilder
$ open docs/html/index.html

Documentation is automatically generated from these source files every time you push your code to GitHub. The post-commit hook is handled by ReadTheDocs and the results are visible at http://readthedocs.org/docs/spinchimp.

Checklist¶

Before every release make sure that:

1. You have documented your changes in the HISTORY.rst file.
2. You have modified the version identifier in the version.txt to reflect the new release.
3. You have confirmed that the package description (generated from README.rst and others) renders correctly by running bin/longtest.
4. You have committed all changes to the git repository and pushed them upstream.
5. You have the working directory checked out at the revision you wish to release.

Actions¶

For help with releasing we use jarn.mkreleaser. It’s listed as a dependency in setup.py and should already be installed in your local bin:

$ bin/mkrelease -d pypi -pq ./

[distutils]
index-servers =
  pypi

[pypi]
username = fred
password = secret

Example¶

In the following example we are releasing version 0.1 of spinchimp. The package has been prepared so that version.txt contains the version 0.1, this change has been committed to git and all changes have been pushed upstream to GitHub:

# Check that package description is rendered correctly
$ bin/longtest

# Make a release and upload it to PyPI
$ bin/mkrelease -d pypi -pq ./
Releasing spinchimp 0.1
Tagging spinchimp 0.1
To git@github.com:niteoweb/spinchimp.git
* [new tag]         0.1 -> 0.1
running egg_info
running sdist
warning: sdist: standard file not found: should have one of README, README.txt
running register
Server response (200): OK
running upload
warning: sdist: standard file not found: should have one of README, README.txt
Server response (200): OK
done