::
_ _
| | | |
| |__ _____ ____ ____ ___ ____| | _
| _ \(____ | \| \ / _ \ / ___) |_/ )
| | | / ___ | | | | | | | |_| ( (___| _ (
|_| |_\_____|_|_|_|_|_|_|\___/ \____)_| \_)
Hammock is a fun module lets you deal with rest APIs by converting them into dead simple programmatic APIs.
It uses popular ``requests`` module in backyard to provide full-fledged rest experience.
Proof
-----
Let's play with github::
>>> from hammock import Hammock as Github
>>> # Let's create the first chain of hammock using base api url
>>> github = Github('https://api.github.com')
>>> # Ok, let the magic happens, ask github for hammock watchers
>>> resp = github.repos('kadirpekel', 'hammock').watchers.GET()
>>> # now you're ready to take a rest for the rest the of code :)
>>> for watcher in resp.json: print watcher.get('login')
kadirpekel
...
..
.
Not convinced? This is also how you can watch this project to see its future capabilities::
>>> github.user.watched('kadirpekel', 'hammock').PUT(auth=('<user>', '<pass>'),
headers={'content-length': '0'})
<Response [204]>
How?
----
``Hammock`` is a thin wrapper over ``requests`` module, you are still with it. But it simplifies your life
by letting you place your variables into URLs naturally by using object notation way. Also you can wrap some
url fragments into objects for improving code re-use. For example;
Take these;
>>> base_url = 'https://api.github.com'
>>> user = 'kadirpekel'
>>> repo = 'hammock'
Without ``Hammock``, using pure ``requests`` module you have to generate your urls by hand using string formatting::
>>> requests.get("%s/repos/%s/%s/watchers" % (base_url, user, repo))
With ``Hammock``, you don't have to deal with string formatting. You can wrap ``base_url`` for code reuse
and easily map variables to urls. This is just cleaner::
>>> github = hammock.Hammock(base_url)
>>> github.repos(user, repo).watchers.GET()
>>> github.user.watched(user, repo).PUT() # reuse!
Install
-------
The best way to install ``Hammock`` is using pypi repositories via ``easy_install`` or ``pip``::
$ pip install hammock
Documentation
-------------
``Hammock`` is a magical, polymorphic(!), fun and simple class which helps you generate RESTful urls
and lets you request them using ``requests`` module in an easy and slick way.
Below the all phrases make requests to the same url of 'http://localhost:8000/users/foo/posts/bar/comments'.
Note that all of them are valid but some of them are nonsense in their belonging context::
>>> import hammock
>>> api = hammock.Hammock('http://localhost:8000')
>>> api.users('foo').posts('bar').comments.GET()
<Response [200]>
>>> api.users.foo.posts('bar').GET('comments')
<Response [200]>
>>> api.users.foo.posts.bar.comments.GET()
<Response [200]>
>>> api.users('foo', 'posts', 'comments').GET()
<Response [200]>
>>> api('users')('foo', 'posts').GET('bar', 'comments')
<Response [200]>
>>> # Any other combinations ...
``Hammock`` class instance provides `requests` module's all http methods binded on itself as uppercased version
while dropping the first arg ``url`` in replacement of ``*args`` to let you to continue appending url components.
Also you can continue providing any keyword argument for corresponding http verb method of ``requests`` module::
Hammock.[GET, HEAD, OPTIONS, POST, PUT, PATCH, DELETE](*args, **kwargs)
Return type is the same ``Response`` object ``requests`` module provides.
Here is some more real world applicable example which uses twitter api::
>>> import hammock
>>> twitter = hammock.Hammock('https://api.twitter.com/1')
>>> tweets = twitter.statuses('user_timeline.json').GET(params={'screen_name':'kadirpekel', 'count':'10'}).json
>>> for tweet in tweets: print tweet.get('text')
my tweets
...
..
.
You might also want to use sessions. Let's take a look at the JIRA example below which maintains basic
auth credentials through several http requests::
>>> import hammock
>>> # You can configure a session by providing keyword args to `Hammock` constructor to initiate builtin `requests` session
>>> # This sample below shows the use of auth credentials through several requests by intitiating a embedded session
>>> jira = hammock.Hammock('https://jira.atlassian.com/rest/api/latest', auth=('<user>', '<pass>'))
>>> my_issue = 'JRA-9'
>>> # Let's get a jira issue. No auth credentials provided explicitly since parent
>>> # hammock already has a `requests` session configured.
>>> issue = jira.issue(my_issue).GET()
>>> # Now watch the issue again using with the same session
>>> watched = jira.issue(my_issue).watchers.POST(params={'name': '<user>'})
>>> print(watched)
Also keep in mind that if you want a trailing slash at the end of URLs generated by ``Hammock``
you should pass ``append_slash`` kewyword argument as ``True`` while constructing ``Hammock``.
For example::
>>> api = hammock.Hammock('http://localhost:8000', append_slash=True)
>>> print (api.foo.bar) # Note that trailing slash
'http://localhost:8000/foo/bar/'
Contributors
------------
* @maraujop (Miguel Araujo)
* @rubik (Michele Lacchia)
Licence
-------
Copyright (c) 2012 Kadir Pekel.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Raw data
{
"_id": null,
"home_page": "https://github.com/kadirpekel/hammock",
"name": "hammock",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Kadir Pekel",
"author_email": "kadirpekel@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c0/4c/a0af8e8c868268a3a24b686e2b82ba6803e0c8c8da3ed89d1099b324ef90/hammock-0.2.4.tar.gz",
"platform": "UNKNOWN",
"description": "::\n\n _ _ \n | | | | \n | |__ _____ ____ ____ ___ ____| | _ \n | _ \\(____ | \\| \\ / _ \\ / ___) |_/ )\n | | | / ___ | | | | | | | |_| ( (___| _ ( \n |_| |_\\_____|_|_|_|_|_|_|\\___/ \\____)_| \\_)\n\nHammock is a fun module lets you deal with rest APIs by converting them into dead simple programmatic APIs.\nIt uses popular ``requests`` module in backyard to provide full-fledged rest experience.\n\nProof\n-----\n\nLet's play with github::\n\n >>> from hammock import Hammock as Github\n\n >>> # Let's create the first chain of hammock using base api url\n >>> github = Github('https://api.github.com')\n\n >>> # Ok, let the magic happens, ask github for hammock watchers\n >>> resp = github.repos('kadirpekel', 'hammock').watchers.GET()\n\n >>> # now you're ready to take a rest for the rest the of code :)\n >>> for watcher in resp.json: print watcher.get('login')\n kadirpekel\n ...\n ..\n .\n\nNot convinced? This is also how you can watch this project to see its future capabilities::\n\n\n >>> github.user.watched('kadirpekel', 'hammock').PUT(auth=('<user>', '<pass>'),\n headers={'content-length': '0'})\n <Response [204]>\n\nHow?\n----\n\n``Hammock`` is a thin wrapper over ``requests`` module, you are still with it. But it simplifies your life\nby letting you place your variables into URLs naturally by using object notation way. Also you can wrap some\nurl fragments into objects for improving code re-use. For example;\n\n\nTake these;\n\n >>> base_url = 'https://api.github.com'\n >>> user = 'kadirpekel'\n >>> repo = 'hammock'\n\nWithout ``Hammock``, using pure ``requests`` module you have to generate your urls by hand using string formatting::\n\n >>> requests.get(\"%s/repos/%s/%s/watchers\" % (base_url, user, repo))\n\nWith ``Hammock``, you don't have to deal with string formatting. You can wrap ``base_url`` for code reuse\nand easily map variables to urls. This is just cleaner::\n\n >>> github = hammock.Hammock(base_url)\n >>> github.repos(user, repo).watchers.GET()\n >>> github.user.watched(user, repo).PUT() # reuse!\n\nInstall\n-------\n\nThe best way to install ``Hammock`` is using pypi repositories via ``easy_install`` or ``pip``::\n\n $ pip install hammock\n\nDocumentation\n-------------\n\n``Hammock`` is a magical, polymorphic(!), fun and simple class which helps you generate RESTful urls\nand lets you request them using ``requests`` module in an easy and slick way.\n\nBelow the all phrases make requests to the same url of 'http://localhost:8000/users/foo/posts/bar/comments'.\nNote that all of them are valid but some of them are nonsense in their belonging context::\n\n >>> import hammock\n >>> api = hammock.Hammock('http://localhost:8000')\n >>> api.users('foo').posts('bar').comments.GET()\n <Response [200]>\n >>> api.users.foo.posts('bar').GET('comments')\n <Response [200]>\n >>> api.users.foo.posts.bar.comments.GET()\n <Response [200]>\n >>> api.users('foo', 'posts', 'comments').GET()\n <Response [200]>\n >>> api('users')('foo', 'posts').GET('bar', 'comments')\n <Response [200]>\n >>> # Any other combinations ...\n\n``Hammock`` class instance provides `requests` module's all http methods binded on itself as uppercased version\nwhile dropping the first arg ``url`` in replacement of ``*args`` to let you to continue appending url components.\n\nAlso you can continue providing any keyword argument for corresponding http verb method of ``requests`` module::\n\n Hammock.[GET, HEAD, OPTIONS, POST, PUT, PATCH, DELETE](*args, **kwargs)\n\nReturn type is the same ``Response`` object ``requests`` module provides.\n\nHere is some more real world applicable example which uses twitter api::\n\n >>> import hammock\n >>> twitter = hammock.Hammock('https://api.twitter.com/1')\n >>> tweets = twitter.statuses('user_timeline.json').GET(params={'screen_name':'kadirpekel', 'count':'10'}).json\n >>> for tweet in tweets: print tweet.get('text')\n my tweets\n ...\n ..\n .\n\nYou might also want to use sessions. Let's take a look at the JIRA example below which maintains basic\nauth credentials through several http requests::\n\n >>> import hammock\n\n >>> # You can configure a session by providing keyword args to `Hammock` constructor to initiate builtin `requests` session\n >>> # This sample below shows the use of auth credentials through several requests by intitiating a embedded session\n >>> jira = hammock.Hammock('https://jira.atlassian.com/rest/api/latest', auth=('<user>', '<pass>'))\n\n >>> my_issue = 'JRA-9'\n\n >>> # Let's get a jira issue. No auth credentials provided explicitly since parent\n >>> # hammock already has a `requests` session configured.\n >>> issue = jira.issue(my_issue).GET()\n\n >>> # Now watch the issue again using with the same session\n >>> watched = jira.issue(my_issue).watchers.POST(params={'name': '<user>'})\n\n >>> print(watched)\n\nAlso keep in mind that if you want a trailing slash at the end of URLs generated by ``Hammock``\nyou should pass ``append_slash`` kewyword argument as ``True`` while constructing ``Hammock``.\nFor example::\n\n >>> api = hammock.Hammock('http://localhost:8000', append_slash=True)\n >>> print (api.foo.bar) # Note that trailing slash\n 'http://localhost:8000/foo/bar/'\n\nContributors\n------------\n\n* @maraujop (Miguel Araujo)\n* @rubik (Michele Lacchia)\n\nLicence\n-------\nCopyright (c) 2012 Kadir Pekel.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n",
"bugtrack_url": null,
"license": "UNKNOWN",
"summary": "rest like a boss",
"version": "0.2.4",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c04ca0af8e8c868268a3a24b686e2b82ba6803e0c8c8da3ed89d1099b324ef90",
"md5": "a2e62d766ac04618c23b7b39a1dcbc5c",
"sha256": "a535f085b7c1c10f675761a8bc8853618cbc66f80d71491eb2486e53ce1f8730"
},
"downloads": -1,
"filename": "hammock-0.2.4.tar.gz",
"has_sig": false,
"md5_digest": "a2e62d766ac04618c23b7b39a1dcbc5c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 4835,
"upload_time": "2013-04-21T21:48:19",
"upload_time_iso_8601": "2013-04-21T21:48:19.907207Z",
"url": "https://files.pythonhosted.org/packages/c0/4c/a0af8e8c868268a3a24b686e2b82ba6803e0c8c8da3ed89d1099b324ef90/hammock-0.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2013-04-21 21:48:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "kadirpekel",
"github_project": "hammock",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "hammock"
}
JSON
