From 8bbd3c03e3fdc03b07b4cd6d89c1ab9b27cdb0e1 Mon Sep 17 00:00:00 2001 From: Marco Tulio R Braga Date: Sat, 27 May 2017 01:27:55 -0300 Subject: [PATCH] [review] Review DOC; Bump version --- CONTRIBUTING.md | 63 ++++++++++++ README.md | 224 ++++++++++++++--------------------------- glpi/glpi.py | 2 + glpi/version.py | 2 +- requirements-dev.txt | 3 + setup.py | 2 +- tests/requirements.txt | 3 +- 7 files changed, 144 insertions(+), 155 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 requirements-dev.txt diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..a1f3367 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,63 @@ +# Questions + +If you are having difficulties using the APIs or have a question about the GLPI-SDK-PYTHON, please ask a question. + +# Issues + +If you encounter an issue with the Python SDK, you are welcome to submit a [bug report](https://github.com/truly-systems/glpi-sdk-python/issues). +Before that, please search for similar issues. It's possible somebody has encountered this issue already. + +## Pull Requests + +If you want to contribute to the repository, here's a quick guide: + 1. Fork the repository + 2. develop and test your code changes with [pytest]. + * Respect the original code [style guide][styleguide]. + * Only use spaces for indentation. + * Create minimal diffs - disable on save actions like reformat source code or organize imports. If you feel the source code should be reformatted create a separate PR for this change. + * Check for unnecessary whitespace with git diff --check before committing. + 3. Make the test pass + 4. Commit your changes + 5. Push to your fork and submit a pull request to the `dev` branch + +## Running the tests + +You probably want to set up a [virtualenv]. + + 1. Clone this repository: + ``` + git clone https://github.com/truly-systems/glpi-sdk-python.git + ``` + 2. Install the sdk as an editable package using the current source: + ``` + pip install --editable . + ``` + 3. Install the test dependencies with: + ``` + pip install -r requirements-dev.txt + ``` + 4. Run the test cases with (now we're only testing PEP8): + ``` + make check-syntax + ``` + +## Aditional tests + +* Install tests dependencies + +`make dependencies` + +* Test PEP8 syntax + +`make check-syntax` + +* Test installation setup + +`make test-setup` + +## Additional Resources ++ [General GitHub documentation](https://help.github.com/) ++ [GitHub pull request documentation](https://help.github.com/send-pull-requests/) + +[styleguide]: http://google.github.io/styleguide/pyguide.html +[virtualenv]: http://virtualenv.readthedocs.org/en/latest/index.html diff --git a/README.md b/README.md index 54a445c..e4b7abd 100644 --- a/README.md +++ b/README.md @@ -8,198 +8,120 @@ GLPI SDK written in Python. ## Description -This SDK is written in Python to help developers integrate their apps, APIS -and scripts in GLPI infrastructure. This SDK abstract the [GLPI Rest API](https://github.com/glpi-project/glpi/blob/9.1/bugfixes/apirest.md) +This SDK is written in Python to help developers integrate their apps, APIS and scripts in GLPI infrastructure. This SDK abstract +the [GLPI Rest API](https://github.com/glpi-project/glpi/blob/9.1/bugfixes/apirest.md). -To usage it, you should have username, password and API-Token from your GLPI -server. +To usage it, you should have username, password and API-Token from your GLPI server. See also: * [GLPI Rest API](https://github.com/glpi-project/glpi/blob/9.1/bugfixes/apirest.md#list-searchoptions) -## SDK supported items - -* Ticket: get, get all, create -* Knowledge Base: get, get all, create ## Install -Just install using pip, from: +Just install from: + +* PyPi: -* Repository: + ```bash + pip install glpi + ``` -`pip install -e git+https://github.com/truly-systems/glpi-sdk-python.git@master#egg=glpi` +* repository (development): -* requirements.txt + ``bash + pip install -e git+https://github.com/truly-systems/glpi-sdk-python.git@master#egg=glpi + ``` -```shell -$ echo '-e git+https://github.com/truly-systems/glpi-sdk-python.git@master#egg=glpi`'\ - > requirements.txt +* requirements.txt (development) -$ pip install -r requirements.txt -``` + ```shell + pip install -r requirements-dev.txt + ``` ## Usage -You should enable the GLPI API and generate an App Token. TO create one follow these steps: +You should enable the GLPI API and generate an App Token. -* TODO +Please, export these environments variables with yours config: -Please, change the vars bellow with yours: + ```python + export username = "GLPI_USER" + password = "GLPI_USER" + url = 'http://glpi.example.com/apirest.php' + glpi_app_token = "GLPI_API_TOKEN" + ``` -```python -username = "GLPI_USER" -password = "GLPI_USER" -url = 'http://glpi.example.com/apirest.php' -glpi_app_token = "GLPI_API_TOKEN" +Then import it in your script and create a `glpi` API connection: -``` + ```python + import os + from glpi import GLPI -### Tickets + url = os.getenv("GLPI_API_URL") or None + user = os.getenv("GLPI_USERNAME") or None + password = os.getenv("GLPI_PASSWORD") or None + token = os.getenv("GLPI_APP_TOKEN") or None -* Get all Tickets + glpi = GLPI(url, token, (user, password)) + ``` -```python -from glpi import GlpiTicket +### Tickets -glpi_ticket = GlpiTicket(url, glpi_app_token, - username=username, - password=password) +* Get all Tickets -tickets_all = glpi_ticket.get_all() -print "Retrieving all tickets: %s" % json.dumps(tickets_all, - indent=4, - separators=(',', ': '), - sort_keys=True) -``` + ```python + print "Getting all Tickets: " + print json.dumps(glpi.get_all('ticket'), + indent=4, + separators=(',', ': '), + sort_keys=True) + ``` * Create an Ticket -```python -from glpi import GlpiTicket, Ticket - -glpi_ticket = GlpiTicket(url, glpi_app_token, - username=username, - password=password) + ```python -ticket = Ticket(name='New ticket from SDK', - content='>>>> Content of ticket created by SDK API <<<') + ticket_payload = { + 'name': 'New ticket from SDK', + 'content': '>>>> Content of ticket created by SDK API <<<' + } -ticket_dict = glpi_ticket.create(ticket_data=ticket) -print "Created the ticket: %s" % ticket_dict + ticket_dict = glpi.create('ticket', ticket_payload) + if isinstance(ticket_dict, dict): + print "The ticket request was sent. See results: " -``` + print json.dumps(ticket_dict, + indent=4, + separators=(',', ': '), + sort_keys=True) + ``` * Get ticket by ID -```python -from glpi import GlpiTicket, Ticket - -glpi_ticket = GlpiTicket(url, glpi_app_token, - username=username, - password=password) - -ticket_dict = {} -ticket_dict['id'] = 1 -ticket_get = glpi_ticket.get(ticket_dict['id']) -print "Got this ticket: %s" % json.dumps(ticket_get, - indent=4, - separators=(',', ': '), - sort_keys=True) - -``` + ```python + print "Getting Ticket with ID 1: " + print json.dumps(glpi.get('ticket', 1), + indent=4, + separators=(',', ': '), + sort_keys=True) + ``` * Profile information -```python -from glpi import GlpiProfile - -glpi_pfl = GlpiProfile(url, - glpi_app_token, username=username, - password=password) - -print "Getting profile " -print json.dumps(glpi_pfl.get_my_profiles(), - indent=4, separators=(',', ': ')) -``` - -* Reusing session token - -```python -token_session = glpi_pfl.get_session_token() -print "Update session for Ticket object: %s" %\ - glpi_ticket.update_session_token(token_session) - -``` + ```python + print "Getting 'My' profile: " + print json.dumps(glpi.get('getMyProfiles'), + indent=4, + separators=(',', ': '), + sort_keys=True) + ``` * Full example -```python -from glpi import GlpiProfile -from glpi import GlpiTicket, Ticket - - -username = "GLPI_USER" -password = "GLPI_USER" -url = 'http://glpi.example.com/apirest.php' -glpi_app_token = "GLPI_API_TOKEN" - - -if __name__ == '__main__': - - glpi_pfl = GlpiProfile(url, - glpi_app_token, username=username, - password=password) - - print "Getting profile " - print json.dumps(glpi_pfl.get_my_profiles(), - indent=4, separators=(',', ': ')) - - token_session = glpi_pfl.get_session_token() - print "Current session is: %s" % token_session - - glpi_ticket = GlpiTicket(url, glpi_app_token, - username=username, - password=password) - - print "Update Ticket object to session: %s" %\ - glpi_ticket.update_session_token(token_session) - - tickets_all = glpi_ticket.get_all() - print "Retrieving all tickets: %s" % json.dumps(tickets_all, - indent=4, - separators=(',', ': '), - sort_keys=True) - - ticket = Ticket(name='New ticket from SDK', - content=' Content of ticket created by SDK API ') - ticket_dict = glpi_ticket.create(ticket_data=ticket) - print "Created the ticket: %s" % ticket_dict - - print "Getting ticket recently created with id %d ..." % ticket_dict['id'] - ticket_get = glpi_ticket.get(ticket_dict['id']) - print "Got this ticket: %s" % json.dumps(ticket_get, - indent=4, - separators=(',', ': '), - sort_keys=True) - -``` - -* TODO: Update with new generic function. See more in tests script `tests/test_glpi_module.py` +>> TODO: create an full example with various Items available in GLPI Rest API. ## CONTRIBUTING -### TEST the code - -* Install tests dependencies - -`make dependencies` - -* Test PEP syntax - -`make check-syntax` - -* Test installation setup - -`make test-setup` +See [CONTRIBUTING.md](CONTRIBUTING.md) diff --git a/glpi/glpi.py b/glpi/glpi.py index 95e940f..2795571 100644 --- a/glpi/glpi.py +++ b/glpi/glpi.py @@ -62,6 +62,7 @@ class GlpiInvalidArgument(GlpiException): class GlpiService(object): """ Polymorphic class of GLPI REST API Service. """ + __version__ = __version__ def __init__(self, url_apirest, token_app, uri, username=None, password=None, token_auth=None, @@ -371,6 +372,7 @@ class GLPI(object): can reuse API sessions. To support new items you should create the dict key/value in item_map. """ + __version__ = __version__ def __init__(self, url, app_token, auth_token, item_map=None): diff --git a/glpi/version.py b/glpi/version.py index df9144c..7fd229a 100644 --- a/glpi/version.py +++ b/glpi/version.py @@ -1 +1 @@ -__version__ = '0.1.1' +__version__ = '0.2.0' diff --git a/requirements-dev.txt b/requirements-dev.txt new file mode 100644 index 0000000..8589d43 --- /dev/null +++ b/requirements-dev.txt @@ -0,0 +1,3 @@ +pep8 +codecov +python-dotenv diff --git a/setup.py b/setup.py index 34b2c7b..062c721 100644 --- a/setup.py +++ b/setup.py @@ -17,7 +17,7 @@ def readme(): description='GLPI API SDK', #long_description=readme(), url='https://github.com/truly-systems/glpi-sdk-python', - download_url='https://github.com/truly-systems/glpi-sdk-python/archive/0.1.1.tar.gz', + download_url='https://github.com/truly-systems/glpi-sdk-python/archive/%s.tar.gz' % __version__, author='Marco Tulio R Braga', author_email='braga@mtulio.eng.br', license='Apache-2.0', diff --git a/tests/requirements.txt b/tests/requirements.txt index 8589d43..d0620e4 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -1,3 +1,2 @@ pep8 -codecov -python-dotenv +git+https://github.com/truly-systems/glpi-sdk-python.git@master#egg=glpi