============
moco-wrapper
============
.. image:: https://img.shields.io/pypi/v/moco_wrapper.svg
:target: https://pypi.python.org/pypi/moco_wrapper
.. image:: https://readthedocs.org/projects/moco-wrapper/badge/?version=master
:target: https://moco-wrapper.readthedocs.io/en/master/?badge=master
:alt: Documentation Status
This is a client implementation of the moco api written in python3.
Installation
------------
From pypi
#########
The moco-wrapper package is available via `pip <https://pypi.org/project/moco-wrapper/>`_.
.. code-block:: shell
$ pip3 install moco-wrapper
From Source
###########
If dont want to use pip you can clone this repository and install it from the source.
.. code-block:: shell
$ git clone https://github.com/sommalia/moco-wrapper moco-wrapper
$ cd ./moco-wrapper
$ pip3 install -r requirements_dev.txt
$ make install
Quickstart
----------
If you already have credentials or an api key you can instantiate your moco-wrapper object like so:
.. code-block:: python
import moco_wrapper
moco = moco_wrapper.Moco(auth={
"api_key": "[MY API KEY]",
"domain": "example" # domain of the moco webapp is example.mocoapp.com
})
With the moco wrapper object you can now interact with moco.
.. code-block:: python
# load a list of users
users = moco.User.getlist()
# load the second page of our list of users
# requests with lists are paginated
# default limit is 100 items per request
users_page_two = moco.User.getlist(page=2)
# create a project
leader = moco.User.getlist()[0]
customer = moco.Company.getlist(type="customer").getlist()[0]
project = moco.Project.create(
name = "my new project",
currency = "EUR",
leader_id = leader.id,
customer_id = customer.id,
finish_date = date(2020, 1, 1)
)
# update a contact
moco.Contact.update(
contact_id = 55123,
lastname = "doe"
)
# add a task to a project
task = moco.Task.create(
project_id = project.id,
name = "My new task"
)
# create a new customer
new_customer = moco.Company.create(
name = "my new customer company",
company_type = moco_wrapper.models.company.CompanyType.CUSTOMER
)
For an overview about all the things that can and cannot be done see
`The Moco Instance <https://moco-wrapper.readthedocs.io/en/latest/code_overview/moco_instance.html>`_.
Tests
-----
There are two types of tests in this repo. *unit*-tests with no side effects
and *integration*-tests that require an actual moco instance (if you want to recreate the cached responses).
Unit
####
These tests check whether all methods can be called correctly, use the
right HTTP method, have the right headers and format everything correctly for the API.
These tests have no side effects and can be run via pytest:
.. code-block:: shell
$ python3 -m pytest tests/unit
Integration
###########
The second group of tests are the *integration* tests.
These tests use the betamax package, send actual requests to a moco instance and save the response locally (see tests/integration/cassettes/).
These tests can also be run via pytest:
.. code-block:: shell
$ python3 -m pytest tests/integration
Recreating the tests results
****************************
If you want to recreate these tests make sure you have the following setup:
* A working, clean moco instance (eg. example.mocoapp.com)
* An api key
* Time to spare
After that you have to export the following variables
.. code-block:: shell
$ export mocotest_apikey=[MY API KEY]
$ export mocotest_domain=example
$ export mocotest_delay=1 # enable delay between tests
The *mocotest_delay* variable will make sure that the api, does not rate limit our test-run
by waiting 5 seconds between the execution of each single test.
**Caution:** Make sure you run the integration tests (if you recreate the results) on a clean moco instance,
as some requests (delete. create and update requests) have side effects, that cannot be reversed easily.
Now that everything is set up we delete the saved responses and re-run the tests.
.. code-block:: shell
$ rm tests/integration/cassettes/*.json
$ python3 -m pytest tests/integration
Documentation
-------------
The full documentation for the moco-wrapper is located at `<https://moco-wrapper.readthedocs.io/>`_.
License
-------
This project is licensed under the GNU Public License - see the `LICENSE`_ file for details
Credits
-------
This package was created with `Cookiecutter`_ and the `audreyr/cookiecutter-pypackage`_ project template.
This package tries to imitate the way that the `praw-package`_, for wrapping around the reddit api, was structured
.. _`Cookiecutter`: https://github.com/audreyr/cookiecutter
.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
.. _`praw-package`: https://github.com/praw-dev/praw
.. _`LICENSE`: https://github.com/sommalia/moco-wrapper/blob/master/LICENSE
.. _`moco-api-readme`: https://github.com/hundertzehn/mocoapp-api-docs
=======
History
=======
0.11.2 (2023-05-23)
-------------------
* Deletion of companies
0.11.1 (2022-04-05)
-------------------
* Create deals with tags
* Getlist of companies with terms
0.11.0 (2021-11-05)
-------------------
* Added support of project destruction
* Added extended service period parameters to project expenses
* Added creating project expenses with files
* Added seconds parameter to activity update for more detailed logging
* Added purchase drafts
* Renamed labels to tags
* Moved file handling into its own helper class
0.10.1 (2021-06-28)
-------------------
* Add support for custom properties in contact, deal, offer and invoice
0.10.0 (2021-04-07)
-------------------
* ListResponses and PagedListResponses now behave like lists
* Changed how api routes are processed
* In the old versions the objector has a map of all routes that are available and how the may back to objects
* Now each model declares the routes by itself and which object will be returned
* In this release the old map, and the old methods are still present, they will be removed in a future release
* Changed the timesheet endpoint of the invoice model to timesheet_pdf for clearer distinction between timesheet_pdf and the new method timesheet_activities
* Renamed HourlyRates model to AccountHourlyRates
* Added verify method to Session model
* Implemented AccountInternalHourlyRates model
* Added getall method to ProjectPaymentSchedule model
* Added more optional parameters to other methods
0.9.0 (2020-12-24)
-------------------
* Reworked response classes
* Split ListingResponse into 2 separate classes
* ListResponse for unpaged response data
* PageListResponse for paginated response data
* Renamed JsonResponse to ObjectResponse
* Implemented taggings endpoint
* Added *clickup* remote service
* Cleaned up tests
0.8.1 (2020-11-17)
------------------
* Removed Project from Schedules (only used for Absences)
* Cleanup tests
* Added deal parameter to project create and update
* Implemented invoice send_email endpoint
* Implemented hourly rates endpoint
0.8.0 (2020-06-28)
------------------
* New Readme
* Add return types to documentation (for default configuration of moco instance only)
* Implement Purchase model
* Allow overwrite of http headers from model classes
* Fix some typos in method names (offer item generator) and parameter (user holidays)
0.7.2 (2020-06-05)
------------------
* Implement update_status endpoint of offer model
0.7.1 (2020-05-30)
------------------
* Create new Releases with bumpversion
* Implemented tags parameter in invoice creation
0.7.0 (2020-05-27)
------------------
* Implemented Planning Entries
* Add credit/debit number to Company
* Add footer to Company
* Add deal property to Project objector model
0.6.3 (2020-04-29)
------------------
* Cleanup
* Fixed example code in documentation
* Fixed various typos
* Implemented contact lookup by phone number and term
0.6.2 (2020-03-24)
------------------
* Query strings conversion into lower case
0.6.1 (2020-03-18)
------------------
* Implement support for days parameter in User holidays
* Implement Purchase Categories
0.6.0 (2020-03-07)
------------------
* Implemented Paging of Listing Models
* Implemented the creation of fixed price projects
* Implement Project Payment Schedules for fixed price projects
* More Documentation and even more code cleanup
0.5.0 (2020-02-29)
------------------
* Implement authentication via email and password (note that the class constructor also changed, if you do not want that continue to ues the previus version (0.4.1))
* Create readthedocs documentation (see https://moco-wrapper.readthedocs.io)
* Error Responses are now converted into actual Exceptions that are raised
* Code Cleanup
0.4.1 (2020-02-24)
------------------
* Implemented impersonation
* Fixed makefile (make test does work now if you have the required packages installed)
* Created documentation see (https://moco-wrapper.readthedocs.io/en/latest/)
* Added named arguments requestor and objector to moco_instance constructor (Setting the requestor via moco.http is no longer possible, user moco.requestor)
* Removed cli component
0.4.0 (2020-02-19)
------------------
* Finished reworking all the integration tests
* Prefixed Employment, Holiday and Presense with "User" for clarification
* Moved duplicated methods id_generator and create_random date into base class
* Implented additional requestor that only tries once to request the api endpoint (no retrying)
* Main moco object moved to namespace moco_wrapper.moco
* Changed author email
0.3.0 (2020-02-17)
------------------
* Create github workflow to automaticly deploy to PyPI
* Implement an objector to control how the json responses get converted back into python objects (some endpoints return data that contain reserved python keywords, this was implemented to circumvent that)
* More Tests and more type hinting
* Write the history of the last versions
* Change the order of things in this history file
* Implement offer creation
0.2.3 (2020-02-09)
------------------
* Implement FileResponses for downloading pdf files from api
* Implement invoice class api changes
* More tests
0.2.2 (2020-01-12)
------------------
* Start implementing type hinting
* Switch to support python3 only
* Remove company delete method, as it is not support by the api
* More Tests
0.2.1 (2020-01-10)
------------------
* More tests
0.1.0 (2019-09-04)
------------------
* First release on PyPI.
Raw data
{
"_id": null,
"home_page": "https://github.com/sommalia/moco-wrapper",
"name": "moco-wrapper",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.5.0",
"maintainer_email": "",
"keywords": "moco_wrapper",
"author": "sommalia",
"author_email": "sommalia@protonmail.com",
"download_url": "https://files.pythonhosted.org/packages/e8/8e/d8394669cab3de66dc7372c75528bb3594725824bac8c5dede8ea552b8c3/moco_wrapper-0.11.2.tar.gz",
"platform": null,
"description": "============\nmoco-wrapper\n============\n\n.. image:: https://img.shields.io/pypi/v/moco_wrapper.svg\n :target: https://pypi.python.org/pypi/moco_wrapper\n\n.. image:: https://readthedocs.org/projects/moco-wrapper/badge/?version=master\n :target: https://moco-wrapper.readthedocs.io/en/master/?badge=master\n :alt: Documentation Status\n\n\nThis is a client implementation of the moco api written in python3.\n\nInstallation\n------------\n\nFrom pypi\n#########\n\nThe moco-wrapper package is available via `pip <https://pypi.org/project/moco-wrapper/>`_.\n\n.. code-block:: shell\n\n $ pip3 install moco-wrapper\n\nFrom Source\n###########\n\nIf dont want to use pip you can clone this repository and install it from the source.\n\n.. code-block:: shell\n\n $ git clone https://github.com/sommalia/moco-wrapper moco-wrapper\n $ cd ./moco-wrapper\n $ pip3 install -r requirements_dev.txt\n $ make install\n\n\nQuickstart\n----------\n\nIf you already have credentials or an api key you can instantiate your moco-wrapper object like so:\n\n.. code-block:: python\n\n import moco_wrapper\n moco = moco_wrapper.Moco(auth={\n \"api_key\": \"[MY API KEY]\",\n \"domain\": \"example\" # domain of the moco webapp is example.mocoapp.com\n })\n\nWith the moco wrapper object you can now interact with moco.\n\n.. code-block:: python\n\n # load a list of users\n users = moco.User.getlist()\n\n # load the second page of our list of users\n # requests with lists are paginated\n # default limit is 100 items per request\n users_page_two = moco.User.getlist(page=2)\n\n # create a project\n leader = moco.User.getlist()[0]\n customer = moco.Company.getlist(type=\"customer\").getlist()[0]\n project = moco.Project.create(\n name = \"my new project\",\n currency = \"EUR\",\n leader_id = leader.id,\n customer_id = customer.id,\n finish_date = date(2020, 1, 1)\n )\n\n # update a contact\n moco.Contact.update(\n contact_id = 55123,\n lastname = \"doe\"\n )\n\n # add a task to a project\n task = moco.Task.create(\n project_id = project.id,\n name = \"My new task\"\n )\n\n # create a new customer\n new_customer = moco.Company.create(\n name = \"my new customer company\",\n company_type = moco_wrapper.models.company.CompanyType.CUSTOMER\n )\n\nFor an overview about all the things that can and cannot be done see\n`The Moco Instance <https://moco-wrapper.readthedocs.io/en/latest/code_overview/moco_instance.html>`_.\n\nTests\n-----\n\nThere are two types of tests in this repo. *unit*-tests with no side effects\nand *integration*-tests that require an actual moco instance (if you want to recreate the cached responses).\n\nUnit\n####\n\nThese tests check whether all methods can be called correctly, use the\nright HTTP method, have the right headers and format everything correctly for the API.\nThese tests have no side effects and can be run via pytest:\n\n.. code-block:: shell\n\n $ python3 -m pytest tests/unit\n\n\nIntegration\n###########\n\nThe second group of tests are the *integration* tests.\nThese tests use the betamax package, send actual requests to a moco instance and save the response locally (see tests/integration/cassettes/).\nThese tests can also be run via pytest:\n\n.. code-block:: shell\n\n $ python3 -m pytest tests/integration\n\nRecreating the tests results\n****************************\n\nIf you want to recreate these tests make sure you have the following setup:\n\n* A working, clean moco instance (eg. example.mocoapp.com)\n* An api key\n* Time to spare\n\nAfter that you have to export the following variables\n\n.. code-block:: shell\n\n $ export mocotest_apikey=[MY API KEY]\n $ export mocotest_domain=example\n $ export mocotest_delay=1 # enable delay between tests\n\nThe *mocotest_delay* variable will make sure that the api, does not rate limit our test-run\nby waiting 5 seconds between the execution of each single test.\n\n**Caution:** Make sure you run the integration tests (if you recreate the results) on a clean moco instance,\nas some requests (delete. create and update requests) have side effects, that cannot be reversed easily.\n\nNow that everything is set up we delete the saved responses and re-run the tests.\n\n.. code-block:: shell\n\n $ rm tests/integration/cassettes/*.json\n $ python3 -m pytest tests/integration\n\n\nDocumentation\n-------------\n\nThe full documentation for the moco-wrapper is located at `<https://moco-wrapper.readthedocs.io/>`_.\n\n\nLicense\n-------\n\nThis project is licensed under the GNU Public License - see the `LICENSE`_ file for details\n\n\nCredits\n-------\n\nThis package was created with `Cookiecutter`_ and the `audreyr/cookiecutter-pypackage`_ project template.\nThis package tries to imitate the way that the `praw-package`_, for wrapping around the reddit api, was structured\n\n.. _`Cookiecutter`: https://github.com/audreyr/cookiecutter\n.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage\n.. _`praw-package`: https://github.com/praw-dev/praw\n.. _`LICENSE`: https://github.com/sommalia/moco-wrapper/blob/master/LICENSE\n.. _`moco-api-readme`: https://github.com/hundertzehn/mocoapp-api-docs\n\n\n\n\n\n=======\nHistory\n=======\n\n0.11.2 (2023-05-23)\n-------------------\n\n* Deletion of companies\n\n0.11.1 (2022-04-05)\n-------------------\n\n* Create deals with tags\n* Getlist of companies with terms\n\n\n0.11.0 (2021-11-05)\n-------------------\n\n* Added support of project destruction\n* Added extended service period parameters to project expenses\n* Added creating project expenses with files\n* Added seconds parameter to activity update for more detailed logging\n* Added purchase drafts\n* Renamed labels to tags\n* Moved file handling into its own helper class\n\n\n0.10.1 (2021-06-28)\n-------------------\n\n* Add support for custom properties in contact, deal, offer and invoice\n\n0.10.0 (2021-04-07)\n-------------------\n\n* ListResponses and PagedListResponses now behave like lists\n* Changed how api routes are processed\n * In the old versions the objector has a map of all routes that are available and how the may back to objects\n * Now each model declares the routes by itself and which object will be returned\n * In this release the old map, and the old methods are still present, they will be removed in a future release\n* Changed the timesheet endpoint of the invoice model to timesheet_pdf for clearer distinction between timesheet_pdf and the new method timesheet_activities\n* Renamed HourlyRates model to AccountHourlyRates\n* Added verify method to Session model\n* Implemented AccountInternalHourlyRates model\n* Added getall method to ProjectPaymentSchedule model\n* Added more optional parameters to other methods\n\n\n0.9.0 (2020-12-24)\n-------------------\n\n* Reworked response classes\n * Split ListingResponse into 2 separate classes\n * ListResponse for unpaged response data\n * PageListResponse for paginated response data\n * Renamed JsonResponse to ObjectResponse\n* Implemented taggings endpoint\n* Added *clickup* remote service\n* Cleaned up tests\n\n0.8.1 (2020-11-17)\n------------------\n\n* Removed Project from Schedules (only used for Absences)\n* Cleanup tests\n* Added deal parameter to project create and update\n* Implemented invoice send_email endpoint\n* Implemented hourly rates endpoint\n\n\n0.8.0 (2020-06-28)\n------------------\n\n* New Readme\n* Add return types to documentation (for default configuration of moco instance only)\n* Implement Purchase model\n* Allow overwrite of http headers from model classes\n* Fix some typos in method names (offer item generator) and parameter (user holidays)\n\n\n0.7.2 (2020-06-05)\n------------------\n\n* Implement update_status endpoint of offer model\n\n0.7.1 (2020-05-30)\n------------------\n\n* Create new Releases with bumpversion\n* Implemented tags parameter in invoice creation\n\n0.7.0 (2020-05-27)\n------------------\n\n* Implemented Planning Entries\n* Add credit/debit number to Company\n* Add footer to Company\n* Add deal property to Project objector model\n\n0.6.3 (2020-04-29)\n------------------\n\n* Cleanup\n* Fixed example code in documentation\n* Fixed various typos\n* Implemented contact lookup by phone number and term\n\n0.6.2 (2020-03-24)\n------------------\n\n* Query strings conversion into lower case\n\n0.6.1 (2020-03-18)\n------------------\n\n* Implement support for days parameter in User holidays\n* Implement Purchase Categories\n\n0.6.0 (2020-03-07)\n------------------\n\n* Implemented Paging of Listing Models\n* Implemented the creation of fixed price projects\n* Implement Project Payment Schedules for fixed price projects\n* More Documentation and even more code cleanup\n\n0.5.0 (2020-02-29)\n------------------\n\n* Implement authentication via email and password (note that the class constructor also changed, if you do not want that continue to ues the previus version (0.4.1))\n* Create readthedocs documentation (see https://moco-wrapper.readthedocs.io)\n* Error Responses are now converted into actual Exceptions that are raised\n* Code Cleanup\n\n0.4.1 (2020-02-24)\n------------------\n\n* Implemented impersonation\n* Fixed makefile (make test does work now if you have the required packages installed)\n* Created documentation see (https://moco-wrapper.readthedocs.io/en/latest/)\n* Added named arguments requestor and objector to moco_instance constructor (Setting the requestor via moco.http is no longer possible, user moco.requestor)\n* Removed cli component\n\n\n0.4.0 (2020-02-19)\n------------------\n\n* Finished reworking all the integration tests\n* Prefixed Employment, Holiday and Presense with \"User\" for clarification\n* Moved duplicated methods id_generator and create_random date into base class\n* Implented additional requestor that only tries once to request the api endpoint (no retrying)\n* Main moco object moved to namespace moco_wrapper.moco\n* Changed author email\n\n\n0.3.0 (2020-02-17)\n------------------\n\n* Create github workflow to automaticly deploy to PyPI\n* Implement an objector to control how the json responses get converted back into python objects (some endpoints return data that contain reserved python keywords, this was implemented to circumvent that)\n* More Tests and more type hinting\n* Write the history of the last versions\n* Change the order of things in this history file\n* Implement offer creation\n\n0.2.3 (2020-02-09)\n------------------\n\n* Implement FileResponses for downloading pdf files from api\n* Implement invoice class api changes\n* More tests\n\n0.2.2 (2020-01-12)\n------------------\n\n* Start implementing type hinting\n* Switch to support python3 only\n* Remove company delete method, as it is not support by the api\n* More Tests\n\n0.2.1 (2020-01-10)\n------------------\n\n* More tests\n\n0.1.0 (2019-09-04)\n------------------\n\n* First release on PyPI.\n\n\n",
"bugtrack_url": null,
"license": "GNU General Public License v3",
"summary": "Wrapper package for using the moco api interface",
"version": "0.11.2",
"project_urls": {
"Homepage": "https://github.com/sommalia/moco-wrapper"
},
"split_keywords": [
"moco_wrapper"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "911f812a33ffd97f5603a78138d5dfe6d523d6ce7ababba6316c5ad923a39a40",
"md5": "ae57111ab06774910f98f5e83f579d5d",
"sha256": "609ae8569589b1783c0145399e3ece24308d8836161911696ffd80253614d635"
},
"downloads": -1,
"filename": "moco_wrapper-0.11.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "ae57111ab06774910f98f5e83f579d5d",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.5.0",
"size": 121693,
"upload_time": "2023-05-23T05:55:36",
"upload_time_iso_8601": "2023-05-23T05:55:36.345441Z",
"url": "https://files.pythonhosted.org/packages/91/1f/812a33ffd97f5603a78138d5dfe6d523d6ce7ababba6316c5ad923a39a40/moco_wrapper-0.11.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e88ed8394669cab3de66dc7372c75528bb3594725824bac8c5dede8ea552b8c3",
"md5": "c3ba760ec85ee6fefe00fded160d1c27",
"sha256": "3ac6dcc153b9c8a04491e041cc9a5868360ca849ab8662d2e08884f83d281fd8"
},
"downloads": -1,
"filename": "moco_wrapper-0.11.2.tar.gz",
"has_sig": false,
"md5_digest": "c3ba760ec85ee6fefe00fded160d1c27",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5.0",
"size": 470697,
"upload_time": "2023-05-23T05:55:39",
"upload_time_iso_8601": "2023-05-23T05:55:39.303748Z",
"url": "https://files.pythonhosted.org/packages/e8/8e/d8394669cab3de66dc7372c75528bb3594725824bac8c5dede8ea552b8c3/moco_wrapper-0.11.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-23 05:55:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sommalia",
"github_project": "moco-wrapper",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "moco-wrapper"
}
JSON
