Welcome

Welcome

pins, a library for organizing and sharing data.

The pins package publishes data, models, and other Python objects, making it easy to share You can pin objects to a variety of pin boards, including folders (to share on a networked drive or with services like DropBox), RStudio Connect, Amazon S3, and Google Cloud Storage. Pins can be automatically versioned, making it straightforward to track changes, re-run analyses on historical data, and undo mistakes.

Installation

To install the released version from PyPI:

python -m pip install pins

Usage

To use the pins package, you must first create a pin board. A good place to start is board_folder(), which stores pins in a directory you specify. Here I’ll use a special version of board_folder() called board_temp() which creates a temporary board that’s automatically deleted when your Python session ends. This is great for examples, but obviously you shouldn’t use it for real work!

from pins import board_temp
from pins.data import mtcars

board = board_temp()
board
<pins.boards.BaseBoard at 0x7f066cf50a60>

You can “pin” (save) data to a board with the .pin_write() method. It requires three arguments: an object, a name, and a pin type:

board.pin_write(mtcars.head(), "mtcars", type="csv")
Writing pin:
Name: 'mtcars'
Version: 20220808T163755Z-120a5
Meta(title='mtcars: a pinned 5 x 11 DataFrame', description=None, created='20220808T163755Z', pin_hash='120a54f7e0818041', file='mtcars.csv', file_size=249, type='csv', api_version=1, version=Version(created=datetime.datetime(2022, 8, 8, 16, 37, 55, 785387), hash='120a54f7e0818041'), name='mtcars', user={})

Above, we saved the data as a CSV, but depending on what you’re saving and who else you want to read it, you might use the type argument to instead save it as a joblib or arrow file (NOTE: arrow is not yet supported).

You can later retrieve the pinned data with .pin_read():

board.pin_read("mtcars")
mpg cyl disp hp drat wt qsec vs am gear carb
0 21.0 6 160.0 110 3.90 2.620 16.46 0 1 4 4
1 21.0 6 160.0 110 3.90 2.875 17.02 0 1 4 4
2 22.8 4 108.0 93 3.85 2.320 18.61 1 1 4 1
3 21.4 6 258.0 110 3.08 3.215 19.44 1 0 3 1
4 18.7 8 360.0 175 3.15 3.440 17.02 0 0 3 2

A board on your computer is good place to start, but the real power of pins comes when you use a board that’s shared with multiple people. To get started, you can use board_folder() with a directory on a shared drive or in DropBox, or if you use RStudio Connect you can use board_rsconnect():

🚧 TODO: add informational messages shown in display below

from pins import board_rsconnect

board = board_rsconnect()
#> Connecting to RSC 1.9.0.1 at <https://connect.rstudioservices.com>

board.pin_write(tidy_sales_data, "hadley/sales-summary", type = "csv")
#> Writing to pin 'hadley/sales-summary'

Then, someone else (or an automated report) can read and use your pin:

board = board_rsconnect()
board.pin_read("hadley/sales-summary")

You can easily control who gets to access the data using the RStudio Connect permissions pane.

The pins package also includes boards that allow you to share data on services like Amazon’s S3 (board_s3()) and Google Cloud Storage (board_gcs()). Learn more in getting started.