PurgoMalum 1.0.3
A python client for the PurgoMalum profanity filter web service
Keywords: profanity,filter,PurgoMalum,purgomalum,purgo_malum,purgo-malum,Purgo Malum

PurgoMalum Client
=================

This is a Python client for the
`PurgoMalum <https://www.purgomalum.com/index.html>`__ web service.

Installation
------------

::

    pip install purgomalum

or

::

    python setup.py install

Usage
-----

To use the basic filtering you can call the ``contains_profanity`` or
the ``retrieve_filtered_text`` methods from the client:

::

    >>> from purgo_malum import client
    >>> client.contains_profanity('You are an @a$$hole')
    True

    >>> client.retrieve_filtered_text('You are an @a$$hole')
    u'You are an ********'

The client functions also support adding words to the profanity list,
setting your own filter text, and setting your own filter characters:

::

    >>> from purgo_malum import client
    >>> client.contains_profanity('You are a good friend', add='you')
    True

    >>> client.retrieve_filtered_text('You are a good friend', add='you,are', fill_text='[filtered]')
    u'[filtered]  [filtered] a good friend'

    >>> client.retrieve_filtered_text('You are a good friend', add='you,are', fill_char='|')
    u'||| ||| a good friend'

You can also get the raw data that the PurgoMalum API returns by calling
the ``raw`` version of the APIs:

::

    >>> from purgo_malum import client
    >>> client.retrieve_filtered_text_raw('You are an @a$$hole', 'json')
    {u'result': u'You are an ********'}
    >>> client.retrieve_filtered_text_raw('You are an @a$$hole', 'plain')
    u'You are an ********'
    >>> client.retrieve_filtered_text_raw('You are an @a$$hole', 'xml')
    u'<?xml version="1.0" encoding="UTF-8" standalone="yes"?><PurgoMalum xmlns="http://www.purgomalum.com"><result>You are an ********</result></PurgoMalum>'

This can be helpful in the event that the API changes and/or you feel
you can use the raw data in some manner.

You can also see the URL that is created for a specific request by using
the ``build_url`` method (mainly helpful for testing):

::

    >>> client.build_url('test text', 'json', add='test', fill_text='[filtered]')
    u'https://www.purgomalum.com/service/json?text=test+text&add=test&fill_text=%5Bfiltered%5D'

Testing
-------

Tests have been for python 2.7 and python 3 using ``pytest``. The unit
tests do call the actual PurgoMalum production API in order to test
against potential API changes.

Before running tests make sure to install
`pytest <https://pypi.org/project/pytest/>`__,
`pytest-cov <https://pypi.org/project/pytest-cov/>`__,
`pytest-mock <https://pypi.org/project/pytest-mock/>`__, and
`mock <https://pypi.org/project/mock/>`__ (already included in
`requirements.txt <requirements.txt>`__).

To execute the tests and generate a code coverage report run the
following:

::

    pytest --cov-report term-missing --cov=purgo_malum/

You should see:

::

    Name                      Stmts   Miss  Cover   Missing
    -------------------------------------------------------
    purgo_malum/__init__.py       0      0   100%
    purgo_malum/client.py        54      0   100%
    -------------------------------------------------------
    TOTAL                        54      0   100%

Miscellaneous
-------------

This is my first offering to the open source community. If you see any
issues with this client library and/or potential improvements please let
me know and I will make the necessary updates.

Donation
--------

If this is helpful to you in any please consider a small donation.

|paypal|

.. |paypal| image:: https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif
   :target: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=GFDDW292XZVDJ&source=url