DOCSEARCHbyAlgolia
Submit Docs

Pinboard.py

repository·master·Indexed 43 days ago

https://github.com/lionheart/pinboard.py

A Python wrapper and command-line utility for the Pinboard.in API. It allows users to programmatically manage bookmarks, tags, and notes. The library provides a one-to-one mapping with the Pinboard API, including a CLI for adding, deleting, and retrieving bookmarks, as well as managing account metadata like RSS keys and API tokens.

Tokens
3.7K
Snippets
18
Records
20
Agent score
51%

What's inside Pinboard.py

  1. How Pinboard.py maps to the Pinboard API

    master
    The library is designed to map one-to-one with the Pinboard API. For example, a call to pb.one.two.three() will trigger a request to https://api.pinboard.in/v1/one/two/three. This allows developers to use the library as a direct proxy for any Pinboard API endpoint.

  2. Understand Pinboard API field mapping

    master

    Pinboard.py maps one-to-one with the Pinboard API. Because the Pinboard API follows the legacy Delicious API naming conventions, the field names in this library may seem counter-intuitive:

    • description in the library corresponds to the Title of the bookmark.
    • extended in the library corresponds to the Description of the bookmark.

    This mapping is maintained to ensure consistency with the underlying Pinboard API.

  4. Authenticate the pinboard CLI

    master

    The pinboard command-line utility requires your Pinboard API token. It looks for credentials in the following order:

    1. The ~/.pinboardrc configuration file.
    2. The PINBOARD_TOKEN environment variable.
    3. An interactive shell prompt (if no other method is found).

    You can force the interactive login process by running pinboard login.

    $ pinboard login
Enter your Pinboard API token: username:XXXXX
Saved Pinboard credentials to ~/.pinboardrc

  5. Initialize the Pinboard client

    master

    To use the library, import pinboard and instantiate the Pinboard class using your API token. You can find your token on the Pinboard password page.

    import pinboard
pb = pinboard.Pinboard('API_TOKEN')
    import pinboard
pb = pinboard.Pinboard('API_TOKEN')

  6. Configure the pinboard CLI authentication

    master

    The pinboard command-line utility requires your Pinboard API token. It attempts to find the token in the following order:

    1. The ~/.pinboardrc configuration file.
    2. The PINBOARD_TOKEN environment variable.
    3. An interactive shell prompt (if the first two methods fail).

    You can explicitly trigger the interactive login process by running pinboard login.

    $ pinboard login
Enter your Pinboard API token: username:XXXXX
Saved Pinboard credentials to ~/.pinboardrc

  7. Build and run the pinboard CLI in Docker

    master

    You can containerize the pinboard CLI using Docker.

    1. Build the image: Navigate to the bin directory of the repository and build the image.

    2. Run the container: Pass the PINBOARD_TOKEN environment variable to the container using the -e flag.

    # Build
$ cd <path_to_pinboard>/bin
$ docker build -t pinboard .

# Run
$ export PINBOARD_TOKEN=<your_pinboard_token>
$ docker run -ti -e PINBOARD_TOKEN pinboard bookmarks --count 10
    $ cd <path_to_pinboard>/bin
$ docker build -t pinboard .

$ export PINBOARD_TOKEN=<your_pinboard_token>
$ docker run -ti -e PINBOARD_TOKEN pinboard bookmarks --count 10

  8. Authenticate with the Pinboard CLI

    master

    To use the CLI, you must provide a Pinboard API token. You can authenticate in two ways:

    1. Interactive Login: Run the login command. The CLI will prompt you to enter your API token and will save it to ~/.pinboardrc for future use.
    2. Environment Variable: Set the PINBOARD_TOKEN environment variable.

    If no token is found in the environment or the config file, the CLI will prompt you for one.

    pinboard login

  9. Get raw API responses

    master

    By default, pinboard.py returns parsed JSON objects. If you need the raw response object (e.g., to read the raw body), pass parse_response=False to any method call.

    response = pb.tags.get(parse_response=False)
print(response.read())
    response = pb.tags.get(parse_response=False)

  10. Manage tags with pb.tags

    master

    The pb.tags object allows you to manage your Pinboard tags.

    • Suggest tags: Use pb.posts.suggest(url='...') to get popular or recommended tags for a specific URL.
    • Get all tags: pb.tags.get() returns a list of Tag objects containing the name and the count of how many times they are used.
    • Delete a tag: pb.tags.delete(tag='...') removes a tag from your account.
    • Rename a tag: pb.tags.rename(old='...', new='...') changes an existing tag name.
    # Suggest tags
pb.posts.suggest(url="https://pinboard.in")

# Get all tags
pb.tags.get()

# Delete a tag
pb.tags.delete(tag="zynga")

# Rename a tag
pb.tags.rename(old='ppython', new='python')

  11. Manage bookmarks with pb.posts

    master

    The pb.posts object provides methods to interact with your bookmarks.

    Add a bookmark

    Use pb.posts.add() with parameters like url, description, extended, tags, shared, and toread.

    pb.posts.add(url="http://google.com/", description="A Great Search Engine", extended="This is a description!", tags=["search", "tools"], shared=True, toread=False)

    Update a bookmark

    To update a bookmark, first retrieve it using pb.posts.get(url=...). You can then modify attributes directly on the Bookmark object and call .save().

    Note on field names: To maintain consistency with the Pinboard API, description refers to the bookmark's title, and extended refers to the bookmark's description.

    # 1. Retrieve
bookmark = pb.posts.get(url='http://google.com/')['posts'][0]

# 2. Modify attributes
bookmark.description = "Google is pretty awesome"
bookmark.tags = ["search", "searching"]

# 3. Save changes
bookmark.save()

    Updating the creation time: If you want to update the bookmark's creation date (time) as well, you must pass 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

    pb.posts.delete(url="http://google.com/")

    Retrieve bookmarks

    • By URL: pb.posts.get(url="...") returns a dictionary containing the date and a list of matching posts.
    • By Date: pb.posts.get(dt=datetime.date.today()) returns posts for a specific day.
    • Recent posts: pb.posts.recent(tag=["tag1", "tag2"]) returns recent bookmarks, optionally filtered by tags.
    • All bookmarks: pb.posts.all(tag=["tag"], start=0, results=100, fromdt=datetime_obj) returns all bookmarks in your account with optional filtering.
    • Post counts by date: pb.posts.dates(tag=["tag"]) returns a dictionary mapping dates to the number of posts on those dates.
    bookmark = pb.posts.get(url='http://google.com/')['posts'][0]
bookmark.description = "New Title"
bookmark.save()

  12. Reference: pinboard CLI subcommands

    master

    The following positional arguments are available for the pinboard command:

    • 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
    • login: interactive login
    {login,last-update,add,delete,get,recent,dates,bookmarks,suggest-tags,tags,delete-tag,rename-tag,notes,note,rss-key,api-token}