Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lionheart/pinboard.py
A full-featured Python wrapper (and command-line utility) for the Pinboard API. Built by the makers of Pushpin for Pinboard.
https://github.com/lionheart/pinboard.py
pinboard python
Last synced: 12 days ago
JSON representation
A full-featured Python wrapper (and command-line utility) for the Pinboard API. Built by the makers of Pushpin for Pinboard.
- Host: GitHub
- URL: https://github.com/lionheart/pinboard.py
- Owner: lionheart
- License: apache-2.0
- Created: 2014-07-24T18:48:52.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2023-07-29T13:05:05.000Z (over 1 year ago)
- Last Synced: 2024-10-01T06:58:09.178Z (about 1 month ago)
- Topics: pinboard, python
- Language: Python
- Homepage:
- Size: 238 KB
- Stars: 345
- Watchers: 18
- Forks: 29
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-starred-test - lionheart/pinboard.py - A full-featured Python wrapper (and command-line utility) for the Pinboard API. Built by the makers of Pushpin for Pinboard. (Python)
README
[][lionheart-url]
[![Version][version-image]][version-url]
[![Versions][versions-image]][versions-url]
Pinboard.py is an easy-to-use and fully-functional Python wrapper and [command-line utility](#command-line) for the Pinboard.in API.
## Installation
Pinboard.py is available for download through the Python Package Index (PyPi). You can install it right away using pip or easy_install.
If you're using Python 3 or above:
```bash
pip install "pinboard>=2.0"
```
For Python 2.7:
```bash
pip install "pinboard>=1.0,<2.0"
```
## Usage
To get started, you're going to need to get your Pinboard API token from the [password page](https://pinboard.in/settings/password) on the Pinboard website. Once you've got that, you're ready to go.
```pycon
>>> import pinboard
>>> pb = pinboard.Pinboard('API_TOKEN')
```
Once you've done this, you can now use the `pb` object to make calls to the Pinboard API. Here are some examples:
### Update
Returns the most recent time a bookmark was added, updated or deleted.
```pycon
>>> pb.posts.update()
datetime.datetime(2014, 7, 27, 18, 11, 29)
```
### Posts
Add a bookmark:
```pycon
>>> pb.posts.add(url="http://google.com/", description="A Great Search Engine", \
extended="This is a description!", tags=["search", "tools"], shared=True, \
toread=False)
True
```
Update a bookmark:
```pycon
# First, retrieve the bookmark you'd like to edit
>>> bookmark = pb.posts.get(url='http://google.com/')['posts'][0]
>>> bookmark
# You can now change description, extended, shared, toread, tags, or time directly with the bookmark object.
>>> bookmark.description = "Google is pretty awesome"
>>> bookmark.tags = ["search", "searching"]
>>> bookmark.save()
True
# If you want to update the bookmark creation date as well, you'll need to pass in `update_time=True` to the save method
>>> import datetime
>>> bookmark.time = datetime.datetime.now() - datetime.timedelta(days=5)
>>> bookmark.save(update_time=True)
```
Delete a bookmark:
```pycon
>>> pb.posts.delete(url="http://google.com/")
True
```
Get one or more posts on a single day matching the parameters:
```pycon
>>> pb.posts.get(url="http://google.com/")
{u'date': datetime.datetime(2014, 7, 25, 16, 35, 25),
u'posts': [],
u'user': u'dlo'}
>>> import datetime
>>> pb.posts.get(dt=datetime.date.today())
{u'date': datetime.datetime(2014, 7, 25, 16, 35, 25),
u'posts': [,
,
],
u'user': u'dlo'}
```
Return all recent bookmarks (optionally filtering by tag):
```pycon
>>> pb.posts.recent(tag=["programming", "python"])
{u'date': datetime.datetime(2014, 4, 28, 2, 7, 58),
u'posts': [,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
],
u'user': u'dlo'}
```
Return a list of dates with the number of posts at each date:
```pycon
>>> pb.posts.dates(tag=["programming", "python"])
{u'dates': {datetime.date(2008, 12, 5): 1,
datetime.date(2008, 12, 6): 1,
...
datetime.date(2014, 7, 24): 6,
datetime.date(2014, 7, 25): 4},
u'tag': u'programming+python',
u'user': u'dlo'}
```
Get all bookmarks in your account:
```pycon
>>> pb.posts.all()
[
,
...
,
]
```
You can also filter by tag, start, results, fromdt, or todt.
```pycon
>>> import datetime
>>> five_days_ago = datetime.datetime.now() - datetime.timedelta(days=5)
>>> pb.posts.all(tag=["programming"], start=10, results=100, fromdt=five_days_ago)
[
,
...
,
]
```
### Tags
Suggest tags for a given URL:
```pycon
>>> pb.posts.suggest(url="https://pinboard.in")
[{u'popular': [u'pinboard']},
{u'recommended': [u'bookmark',
u'bookmarks',
u'\uc815\ubcf4\ud1b5\uc2e0',
u'pinboard',
u'Unread',
u'webservice']}]
```
Return all tags in your account along with the number of times they were used:
```pycon
>>> pb.tags.get()
[,
,
,
,
,
]
```
Delete a tag:
```pycon
>>> pb.tags.delete(tag="zynga")
True
```
Rename a tag:
```pycon
>>> pb.tags.rename(old='ppython', new='python')
True
```
### Miscellaneous
By default, pinboard.py will return parsed JSON objects. If you'd like the raw response object for a request, just pass in `parse_response=False`.
```pycon
>>> response = pb.tags.get(parse_response=False)
>>> response
>
>>> response.read()
... your tags ...
```
Pinboard.py maps one-to-one with the Pinboard API (e.g., `pb.one.two.three()` will send a request to "https://api.pinboard.in/v1/one/two/three"). For more information on other methods and usage, please refer to the [Pinboard API documentation](https://pinboard.in/api/).
One more note--you might have noticed that there is no "title" attribute for bookmarks. I promise you, there's a good reason for this! This has been done since the Pinboard API calls titles "descriptions" and descriptions "extended" (which, interestingly, was done to stay consistent with the Delicious API, which the Pinboard API was modeled after). In order to keep things minimally confusing, this library sticks to how the Pinboard API names these fields. Just remember--"description" means "title" and "extended" means "description".
## Command Line
In addition to providing full Python-level support for the Pinboard API, pinboard.py also comes bundled with a handy command-line utility called "pinboard". Just type "pinboard -h" for a full list of supported commands. Your API token needs to be available to pinboard.py, and can be entered in several ways. Firstly pinboard.py will try to read the ~/.pinboardrc configuration file. If not present then it will try to read an environment variable called `PINBOARD_TOKEN`. Lastly it will show a shell prompt for the user to enter their token (you can immediately force the latter behavior by typing `pinboard login`).
All of the commands pre-process and indent the JSON output. If you would like to shoot the raw response data to stdout, just pass "--raw" before the subcommand (e.g., "pinboard --raw bookmarks").
Examples:
```sh
$ pinboard login
Enter your Pinboard API token: username:XXXXX
Saved Pinboard credentials to ~/.pinboardrc
$ pinboard suggest-tags --url http://pymotw.com/2/argparse/
[
{
"popular": [
"python"
]
},
{
"recommended": [
"python",
"argument",
"parsing"
]
}
]
$ pinboard get --date 7-13-2014
{
"date": "2014-07-13T03:03:58Z",
"posts": [
{
"extended": "",
"hash": "e2311835eb0de6bff2595a9b1525bb98",
"description": "Python 2.7.x and Python 3.x key differences",
"tags": "python",
"href": "http://sebastianraschka.com/Articles/2014_python_2_3_key_diff.html",
"meta": "561d1f53791a8c50109393411f0301fc",
"time": "2014-07-13T03:03:58Z",
"shared": "yes",
"toread": "no"
},
{
"extended": "",
"hash": "4abe28f70154bd35f84be73cec0c53ef",
"description": "Miami, the great world city, is drowning while the powers that be look away | World news | The Observer",
"tags": "",
"href": "http://www.theguardian.com/world/2014/jul/11/miami-drowning-climate-change-deniers-sea-levels-rising",
"meta": "2ca547789553ba9d3202a5cd3d367685",
"time": "2014-07-13T02:53:54Z",
"shared": "yes",
"toread": "yes"
}
],
"user": "dlo"
}
$ pinboard --raw get --date 7/13/2014
{"date":"2014-07-13T03:03:58Z","user":"dlo","posts":[{"href":"http:\/\/sebastianraschka.com\/Articles\/2014_python_2_3_key_diff.html","description":"Python 2.7.x and Python 3.x key differences","extended":"","meta":"561d1f53791a8c50109393411f0301fc","hash":"e2311835eb0de6bff2595a9b1525bb98","time":"2014-07-13T03:03:58Z","shared":"yes","toread":"no","tags":"python"},{"href":"http:\/\/www.theguardian.com\/world\/2014\/jul\/11\/miami-drowning-climate-change-deniers-sea-levels-rising","description":"Miami, the great world city, is drowning while the powers that be look away | World news | The Observer","extended":"","meta":"2ca547789553ba9d3202a5cd3d367685","hash":"4abe28f70154bd35f84be73cec0c53ef","time":"2014-07-13T02:53:54Z","shared":"yes","toread":"yes","tags":""}]}
```
You can print a full list of pinboard commands by passing the "-h" flag.
```sh
$ pinboard -h
usage: pinboard [-h] [--raw]
{login,last-update,add,delete,get,recent,dates,bookmarks,suggest-tags,tags,delete-tag,rename-tag,notes,note,rss-key,api-token}
...
positional arguments:
{login,last-update,add,delete,get,recent,dates,bookmarks,suggest-tags,tags,delete-tag,rename-tag,notes,note,rss-key,api-token}
add posts/add
delete posts/delete
get posts/get
recent posts/recent
dates posts/dates
bookmarks posts/all
suggest-tags posts/suggest
tags tags/get
delete-tag tags/delete
rename-tag tags/rename
notes notes/list
note notes/ID
rss-key user/secret
api-token user/api_token
optional arguments:
-h, --help show this help message and exit
--raw Print the raw data from the Pinboard API without any
formatting.
```
...or help for a specific subcommand by passing the subcommand and then the "-h" flag.
```sh
$ pinboard bookmarks -h
usage: pinboard bookmarks [-h] [--from_date FROM_DATE] [--to_date TO_DATE]
[--tags TAGS [TAGS ...]] [--count COUNT]
[--offset OFFSET]
optional arguments:
-h, --help show this help message and exit
--from_date FROM_DATE
--to_date TO_DATE
--tags TAGS [TAGS ...]
--count COUNT
--offset OFFSET
```
### Using the CLI in Docker
To build the CLI in Docker:
```sh
$ cd /bin
$ docker build -t pinboard .
```
To run the CLI in Docker after building:
```sh
$ export PINBOARD_TOKEN=
$ docker run -ti -e PINBOARD_TOKEN pinboard bookmarks --count 10
```
## Support
If you like this library, you might want to check out [Pushpin for Pinboard](https://itunes.apple.com/us/app/pushpin-for-pinboard/id548052590?mt=8&uo=4&at=1l3vbEC).
## License [![License][license-image]][license-url]
Apache License, Version 2.0. See [LICENSE][license-url] for details.
[license-image]: http://img.shields.io/pypi/l/pinboard.py.svg?style=flat
[license-url]: LICENSE
[version-image]: http://img.shields.io/pypi/v/pinboard.svg?style=flat
[version-url]: https://pypi.python.org/pypi/pinboard
[versions-image]: https://img.shields.io/pypi/pyversions/pinboard.svg?style=flat
[versions-url]: https://pypi.python.org/pypi/pinboard
[lionheart-url]: https://lionheartsw.com/