bookstore :books:¶
bookstore :books: provides tooling and workflow recommendations for storing :cd: , scheduling :calendar:, and publishing :book: notebooks.
Note: Supports installation on Python 3.6 and above. Processes notebooks from Python 2 or Python 3.
Automatic Notebook Versioning¶
Every save of a notebook creates an immutable copy of the notebook on object storage.
To simplify implementation, we currently rely on S3 as the object store, using versioned buckets.
Storage Paths¶
All notebooks are archived to a single versioned S3 bucket with specific prefixes denoting the lifecycle of the notebook:
/workspace
- where users edit/published
- public notebooks (to an organization)
Each notebook path is a namespace that an external service ties into the schedule. We archive off versions, keeping the path intact (until a user changes them).
Prefix | Intent |
---|---|
/workspace/kylek/notebooks/mine.ipynb |
Notebook in “draft” |
/published/kylek/notebooks/mine.ipynb |
Current published copy |
Scheduled notebooks will also be referred to by the notebook key. In addition, we’ll need to be able to surface version IDs as well.
Transitioning to this Storage Plan¶
Since most people are on a regular filesystem, we’ll start with writing to the /workspace
prefix as Archival Storage (writing on save using a post_save_hook
for a Jupyter contents manager).
Publishing¶
The bookstore publishing endpoint is a serverextension to the classic Jupyter server.
This means if you are developing this you will need to explicitly enable it to use the endpoint.
To do so you run: jupyter serverextension enable --py bookstore
.
If you wish to enable it only for your current environment, run: jupyter serverextension enable --py bookstore --sys-prefix
.
Installation¶
bookstore requires Python 3.6 or higher.
- Clone this repo.
- At the repo’s root, enter in the Terminal:
python3 -m pip install .
(Tip: don’t forget the dot at the end of the command)
Configuration¶
# jupyter config
# At ~/.jupyter/jupyter_notebook_config.py for user installs on macOS
# See https://jupyter.readthedocs.io/en/latest/projects/jupyter-directories.html for other places to plop this
from bookstore import BookstoreContentsArchiver
c.NotebookApp.contents_manager_class = BookstoreContentsArchiver
# All Bookstore settings are centralized on one config object so you don't have to configure it for each class
c.BookstoreSettings.workspace_prefix = "/workspace/kylek/notebooks"
c.BookstoreSettings.published_prefix = "/published/kylek/notebooks"
c.BookstoreSettings.s3_bucket = "<bucket-name>"
# Note: if bookstore is used from an EC2 instance with the right IAM role, you don't
# have to specify these
c.BookstoreSettings.s3_access_key_id = <AWS Access Key ID / IAM Access Key ID>
c.BookstoreSettings.s3_secret_access_key = <AWS Secret Access Key / IAM Secret Access Key>
Oh, hello there! You’re probably reading this because you are interested in contributing to nteract. That’s great to hear! This document will help you through your journey of open source. Love it, cherish it, take it out to dinner, but most importantly: read it thoroughly!
What do I need to know to help?¶
Read the README.md file. This will help you set up the project. If you have questions, please ask on the nteract Slack channel. We’re a welcoming project and are happy to answer your questions.
How do I make a contribution?¶
Never made an open source contribution before? Wondering how contributions work in the nteract world? Here’s a quick rundown!
Find an issue that you are interested in addressing or a feature that you would like to address.
Fork the repository associated with the issue to your local GitHub organization.
Clone the repository to your local machine using:
git clone https://github.com/github-username/repository-name.git
Create a new branch for your fix using:
git checkout -b branch-name-here
Make the appropriate changes for the issue you are trying to address or the feature that you want to add.
Confirm that unit tests and linting still pass successfully with:
yarn test
If tests fail, don’t hesitate to ask for help.
Add and commit the changed files using
git add
andgit commit
.Push the changes to the remote repository using:
git push origin branch-name-here
Submit a pull request to the upstream repository.
Title the pull request per the requirements outlined in the section below.
Set the description of the pull request with a brief description of what you did and any questions you might have about what you did.
Wait for the pull request to be reviewed by a maintainer.
Make changes to the pull request if the reviewing maintainer recommends them.
Celebrate your success after your pull request is merged! :tada:
How should I write my commit messages and PR titles?¶
Good commit messages serve at least three important purposes:
- To speed up the reviewing process.
- To help us write a good release note.
- To help the future maintainers of nteract/nteract (it could be you!), say five years into the future, to find out why a particular change was made to the code or why a specific feature was added.
Structure your commit message like this:
> Short (50 chars or less) summary of changes
>
> More detailed explanatory text, if necessary. Wrap it to about 72
> characters or so. In some contexts, the first line is treated as the
> subject of an email and the rest of the text as the body. The blank
> line separating the summary from the body is critical (unless you omit
> the body entirely); tools like rebase can get confused if you run the
> two together.
>
> Further paragraphs come after blank lines.
>
> - Bullet points are okay, too
>
> - Typically a hyphen or asterisk is used for the bullet, preceded by a
> single space, with blank lines in between, but conventions vary here
>
Source: http://git-scm.com/book/ch5-2.html
DO¶
- Write the summary line and description of what you have done in the imperative mode, that is as if you were commanding. Start the line with “Fix”, “Add”, “Change” instead of “Fixed”, “Added”, “Changed”.
- Always leave the second line blank.
- Line break the commit message (to make the commit message readable without having to scroll horizontally in gitk).
DON’T¶
- Don’t end the summary line with a period - it’s a title and titles don’t end with a period.
Tips¶
- If it seems difficult to summarize what your commit does, it may be because it
includes several logical changes or bug fixes, and are better split up into
several commits using
git add -p
.
References¶
The following blog post has a nice discussion of commit messages:
- “On commit messages” http://who-t.blogspot.com/2009/12/on-commit-messages.html
How fast will my PR be merged?¶
Your pull request will be merged as soon as there are maintainers to review it and after tests have passed. You might have to make some changes before your PR is merged but as long as you adhere to the steps above and try your best, you should have no problem getting your PR merged.
That’s it! You’re good to go!
Contributor Code of Conduct¶
As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
We are committed to making participation in this project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
Examples of behavior that contributes to creating a positive environment include:
- Using welcoming and inclusive language
- Being respectful of differing viewpoints and experiences
- Gracefully accepting constructive criticism
- Focusing on what is best for the community
- Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
- The use of sexualized language or imagery and unwelcome sexual attention or advances
- Trolling, insulting/derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others’ private information, such as a physical or electronic address, without explicit permission
- Other conduct which could reasonably be considered inappropriate in a professional setting
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
By adopting this Code of Conduct, project maintainers commit themselves to fairly and consistently applying these principles to every aspect of managing this project. Project maintainers who do not follow or enforce the Code of Conduct may be permanently removed from the project team.
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project maintainer at [rgbkrk@gmail.com]. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. Maintainers are obligated to maintain confidentiality with regard to the reporter of an incident.
This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available from http://contributor-covenant.org/version/1/4/
Releasing¶
Pre-release¶
- [ ] First check that the CHANGELOG is up to date for the next release version.
- [ ] Update docs
Installing twine package¶
Install and upgrade, if needed,twine
with python3 -m pip install -U twine
.
The long description of the package will not render on PyPI unless an up-to-date
version is used.
Create the release¶
- [ ] Update version number
bookstore/_version.py
- [ ] Commit the updated version
- [ ] Clean the repo of all non-tracked files:
git clean -xdfi
- [ ] Commit and tag the release
git commit -am"release $VERSION"
git tag $VERSION
- [ ] Push the tags and remove any existing
dist
directory files
git push && git push --tags
rm -rf dist/*
- [ ] Build
sdist
andwheel
python setup.py sdist
python setup.py bdist_wheel
Test and upload release to PyPI¶
- [ ] Test the wheel and sdist locally
- [ ] Upload to PyPI using
twine
over SSL
twine upload dist/*
- [ ] If all went well:
- Change
bookstore/_version.py
back to.dev
- Push directly to
master
and push--tags
too.
- Change
\ Sort by:\ best rated\ newest\ oldest\
\\
Add a comment\ (markup):
\``code``
, \ code blocks:::
and an indented block after blank line