<p align="center">
<img alt="treasure chest banner image" src="https://github.com/LaurenzBeck/gists/blob/main/docs/artwork/isometric_chest_by_sephiroth_art_da0mr89-375w-2x.jpg?raw=true">
</p>
<h1 align="center">đđĻ Python Gists Importing</h1>
<p align="center">
<a href="https://pypi.org/project/python-gists-import/"><img alt="Static Badge" src="https://img.shields.io/badge/đĻ_version-1.0.1-blue"></a>
<a href="https://www.python.org/"><img alt="Python" src="https://img.shields.io/badge/Python-3.11-yellow?logo=python"></a>
<a href="https://python-poetry.org/"><img alt="Poetry" src="https://img.shields.io/badge/Poetry-1.8.3-blue?logo=Poetry"></a>
<a href="https://github.com/astral-sh/ruff"><img alt="Ruff" src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json"></a>
</p>
<p align="center">
<a href="https://www.repostatus.org/#active"><img src="https://www.repostatus.org/badges/latest/active.svg" alt="Project Status: Active â The project has reached a stable, usable state and is being actively developed." /></a>
<img alt="Static Badge" src="https://badges.frapsoft.com/os/v3/open-source.svg">
<a href="https://opensource.org/license/mit/"><img alt="MIT" src="https://img.shields.io/badge/đī¸_license-MIT-blue"></a>
</p>
<p align="center">
<a href="https://github.com/LaurenzBeck/gists?tab=readme-ov-file#-usage">đĻ Usage</a> âĸ
<a href="https://github.com/laurenzbeck/gists?tab=readme-ov-file#-installation">đ Installation</a> âĸ
<a href="https://github.com/laurenzbeck/gists?tab=readme-ov-file#-motivation">đĄ Motivation</a> âĸ
<a href="https://github.com/laurenzbeck/gists?tab=readme-ov-file#-publishing-a-gist">đ Publishing a Gist</a>
</p>
## đĻ Usage
This package provides a very convenient way to import [GitHub gists](https://docs.github.com/de/get-started/writing-on-github/editing-and-sharing-content-with-gists) directly from Python:
```python
from gists import <gist_id>
```
The first time a gist is imported this way, it will be downloaded using GitHub's API and saved locally as `gists/<gist_id>.py` (The description of the gist will be saved as `gists/<gist_id>.md`). Every subsequent import will not require internet access, as the local copy of the gist will be used.
## đ Installation
The [package](https://pypi.org/project/python-gists-import/) is published on PyPi, so it can be installed with pip using:
```sh
$pip install python-gists-import
```
## đĄ Motivation
During my PhD, I had many ideas and felt confident to work on a few full packages. I discovered that developing packages and everything that comes with them requires a lot of effort and diverse skills including:
+ managing dependencies
+ configuring linters, formatters, task runners ...
+ setting up CI/CD, pre-commit
+ writing technical documentation
+ planning your code organization and namespaces
+ implementing your ideas
+ testing your implementation
+ choosing evocative artwork and emojis đ
+ choosing a license
+ preparing a repository for contributions by adhering to [community guidelines](https://docs.github.com/en/site-policy/github-terms/github-community-guidelines)
One also has to be creative and lucky in finding a short and fitting name, that is still available on PyPi.
That the motivation and energy for working on personal projects and ideas often comes in bursts, does not help either.
While writing a proper Python package is without a doubt the appropriate way to implement and share your moderately complex ideas, smaller ideas suffer from a few problems:
+ the package development overhead is too high
+ bundling all of your ideas into one utility package can quickly become chaotic
+ how do you properly name and advertise a package consisting of a single class or function?
[GitHub gists](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists/creating-gists#about-gists) provide a lightweight deployment alternative to building and publishing a package on PyPi. The user experience of creating and managing them is as easy as it can get (amazing work there đ). Another big advantage is the guaranteed collision-free (though arguably un-relatable) "package name", you get from the gist id.
No one stops you from just downloading a gist manually and placing it in your codebase, but there are other alternatives. [`gist-import`](https://github.com/matteoferla/gist-import/tree/main) is a package very similar in functionality to this one (shout-out to https://github.com/matteoferla for his work on the package đĒ). I even use it in the background because it already contained the gist fetching logic đ
. I recently watched a [PyCon talk](https://www.youtube.com/watch?v=ItOUx7zTcgo) where the Python import machinery was explained in detail, and I simply wanted to play around with the new concepts in my free time.
## đ Publishing a Gist
GitHub has good [documentation on how to create and manage gists](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists/creating-gists) đ.
I will give some additional considerations that are often overlooked.
### đī¸ Licensing
When you want your gist to be used by as many people as possible, it is important to add a license to your gists.
> đ¤ If you want an uncomplicated license that gives your users a lot of freedom, the [MIT license](https://opensource.org/license/mit) is a good default choice.
According to a [blog post](https://zebracatzebra.com/oss/getting-the-gist-of-github-gist-licensing/) from Jeff Luszcz there are two good options:
+ state a default license in the README of your GitHub profile
+ state the license in the gist itself
Because the full license text can be quite large, which would diminish the visual appeal of shorter gists, one can also just mention the name of the license with a copyright date and the copyright owner.
I included an example of this approach in the [đ Template](https://github.com/laurenzbeck/gists?tab=readme-ov-file#-template)
### đ Referencing
Unfortunately, [getting a DOI](https://docs.github.com/de/repositories/archiving-a-github-repository/referencing-and-citing-content) (document object identifier) from Zenodo only works with repositories.
You can, however, include a bibitem in the description of your gist (see the [đ Template](https://github.com/laurenzbeck/gists?tab=readme-ov-file#-template)):
```bibtex
@misc{<bibkey>,
author={<your name>},
title={<the title of your gist>},
year={<year of publication>},
url={https://gist.github.com/<user name>/<gist id>},
}
```
### đ Template
#### Description
````markdown
# Title
> đŽ feel free to delete any section that is not helpful for your description (including this message).
Short description.
## đĻ Usage
How to use the gist with code examples.
## đ¤ Statement of Need
Describe why the code in your gist is needed.
## đ Installation
This gist can be installed using the [`python-gists-import`]() package:
```sh
$pip install python-gists-import
```
After that, simply import the gist in your code via:
```python
from gists import <gist id>
```
### đ Requirements
If your gist depends on other Python packages, include a list of those dependencies here. Users have to manually make sure that they have these dependencies installed. I would suggest using version specifiers used by [poetry](https://python-poetry.org/docs/dependency-specification/):
```toml
python = "^3.11"
```
## đī¸ License and Copyright Šī¸
The code inside this gist is licensed under the [MIT](https://opensource.org/license/mit) license.
Copyright <YEAR> <COPYRIGHT HOLDER>
## đ Cite Me
```bibtex
@misc{<bibkey>,
author={<your name>},
title={<the title of your gist>},
year={<year of publication>},
url={https://gist.github.com/<user name>/<gist id>},
}
```
````
#### Code
```python
"""# module title
module description.
"""
# Copyright <YEAR> <COPYRIGHT HOLDER>
#
# Licensed under the [MIT](https://opensource.org/license/mit) license.
def hello(name: str = "world") -> None:
"""đŖī¸ says hello to `name`."""
print(f"hello, {name}!")
```
---
## đŧī¸ Šī¸ Banner Artwork Attribution
<a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-nc-nd/3.0/88x31.png" /></a><br />The art in the banner of this README is licensed under a [Creative Commons Attribution-NonCommercial-No Derivatives Works 3.0 License](https://creativecommons.org/licenses/by-nc-nd/3.0/). It was made by [sephiroth-art](https://www.deviantart.com/sephiroth-art). Check out his beautiful artwork â¤ī¸
Raw data
{
"_id": null,
"home_page": "https://github.com/LaurenzBeck/gists.git",
"name": "python-gists-import",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "Python, GitHub, gists, import, deployment, \ud83d\udc0d, \ud83d\udce6",
"author": "Farthofer Laurenz",
"author_email": "laurenz@hey.com",
"download_url": "https://files.pythonhosted.org/packages/29/29/af49adb338daf716030ec32e54eebe250c804546532829c5b334d18423d3/python_gists_import-1.0.2.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img alt=\"treasure chest banner image\" src=\"https://github.com/LaurenzBeck/gists/blob/main/docs/artwork/isometric_chest_by_sephiroth_art_da0mr89-375w-2x.jpg?raw=true\">\n</p>\n\n<h1 align=\"center\">\ud83d\udc0d\ud83d\udce6 Python Gists Importing</h1>\n\n<p align=\"center\">\n <a href=\"https://pypi.org/project/python-gists-import/\"><img alt=\"Static Badge\" src=\"https://img.shields.io/badge/\ud83d\udce6_version-1.0.1-blue\"></a>\n <a href=\"https://www.python.org/\"><img alt=\"Python\" src=\"https://img.shields.io/badge/Python-3.11-yellow?logo=python\"></a>\n <a href=\"https://python-poetry.org/\"><img alt=\"Poetry\" src=\"https://img.shields.io/badge/Poetry-1.8.3-blue?logo=Poetry\"></a>\n <a href=\"https://github.com/astral-sh/ruff\"><img alt=\"Ruff\" src=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json\"></a>\n</p>\n<p align=\"center\">\n <a href=\"https://www.repostatus.org/#active\"><img src=\"https://www.repostatus.org/badges/latest/active.svg\" alt=\"Project Status: Active \u2013 The project has reached a stable, usable state and is being actively developed.\" /></a>\n <img alt=\"Static Badge\" src=\"https://badges.frapsoft.com/os/v3/open-source.svg\">\n <a href=\"https://opensource.org/license/mit/\"><img alt=\"MIT\" src=\"https://img.shields.io/badge/\ud83d\udddd\ufe0f_license-MIT-blue\"></a>\n</p>\n\n<p align=\"center\">\n <a href=\"https://github.com/LaurenzBeck/gists?tab=readme-ov-file#-usage\">\ud83d\udce6 Usage</a> \u2022\n <a href=\"https://github.com/laurenzbeck/gists?tab=readme-ov-file#-installation\">\ud83d\udc0d Installation</a> \u2022\n <a href=\"https://github.com/laurenzbeck/gists?tab=readme-ov-file#-motivation\">\ud83d\udca1 Motivation</a> \u2022\n <a href=\"https://github.com/laurenzbeck/gists?tab=readme-ov-file#-publishing-a-gist\">\ud83c\udd99 Publishing a Gist</a>\n</p>\n\n## \ud83d\udce6 Usage\n\nThis package provides a very convenient way to import [GitHub gists](https://docs.github.com/de/get-started/writing-on-github/editing-and-sharing-content-with-gists) directly from Python:\n\n```python\nfrom gists import <gist_id>\n```\n\nThe first time a gist is imported this way, it will be downloaded using GitHub's API and saved locally as `gists/<gist_id>.py` (The description of the gist will be saved as `gists/<gist_id>.md`). Every subsequent import will not require internet access, as the local copy of the gist will be used.\n\n## \ud83d\udc0d Installation\n\nThe [package](https://pypi.org/project/python-gists-import/) is published on PyPi, so it can be installed with pip using:\n\n```sh\n$pip install python-gists-import\n```\n\n## \ud83d\udca1 Motivation\n\nDuring my PhD, I had many ideas and felt confident to work on a few full packages. I discovered that developing packages and everything that comes with them requires a lot of effort and diverse skills including:\n\n+ managing dependencies\n+ configuring linters, formatters, task runners ...\n+ setting up CI/CD, pre-commit\n+ writing technical documentation\n+ planning your code organization and namespaces\n+ implementing your ideas\n+ testing your implementation\n+ choosing evocative artwork and emojis \ud83d\ude09\n+ choosing a license\n+ preparing a repository for contributions by adhering to [community guidelines](https://docs.github.com/en/site-policy/github-terms/github-community-guidelines)\n\nOne also has to be creative and lucky in finding a short and fitting name, that is still available on PyPi.\n\nThat the motivation and energy for working on personal projects and ideas often comes in bursts, does not help either.\n\nWhile writing a proper Python package is without a doubt the appropriate way to implement and share your moderately complex ideas, smaller ideas suffer from a few problems:\n\n+ the package development overhead is too high\n+ bundling all of your ideas into one utility package can quickly become chaotic\n+ how do you properly name and advertise a package consisting of a single class or function?\n\n[GitHub gists](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists/creating-gists#about-gists) provide a lightweight deployment alternative to building and publishing a package on PyPi. The user experience of creating and managing them is as easy as it can get (amazing work there \ud83d\udc96). Another big advantage is the guaranteed collision-free (though arguably un-relatable) \"package name\", you get from the gist id.\n\nNo one stops you from just downloading a gist manually and placing it in your codebase, but there are other alternatives. [`gist-import`](https://github.com/matteoferla/gist-import/tree/main) is a package very similar in functionality to this one (shout-out to https://github.com/matteoferla for his work on the package \ud83d\udcaa). I even use it in the background because it already contained the gist fetching logic \ud83d\ude05. I recently watched a [PyCon talk](https://www.youtube.com/watch?v=ItOUx7zTcgo) where the Python import machinery was explained in detail, and I simply wanted to play around with the new concepts in my free time.\n\n## \ud83c\udd99 Publishing a Gist\n\nGitHub has good [documentation on how to create and manage gists](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists/creating-gists) \ud83d\udcd6.\n\nI will give some additional considerations that are often overlooked.\n\n### \ud83d\udddd\ufe0f Licensing\n\nWhen you want your gist to be used by as many people as possible, it is important to add a license to your gists.\n\n> \ud83e\udd1a If you want an uncomplicated license that gives your users a lot of freedom, the [MIT license](https://opensource.org/license/mit) is a good default choice.\n\nAccording to a [blog post](https://zebracatzebra.com/oss/getting-the-gist-of-github-gist-licensing/) from Jeff Luszcz there are two good options:\n\n+ state a default license in the README of your GitHub profile\n+ state the license in the gist itself\n\nBecause the full license text can be quite large, which would diminish the visual appeal of shorter gists, one can also just mention the name of the license with a copyright date and the copyright owner.\n\nI included an example of this approach in the [\ud83d\udcdd Template](https://github.com/laurenzbeck/gists?tab=readme-ov-file#-template)\n\n### \ud83d\udcd6 Referencing\n\nUnfortunately, [getting a DOI](https://docs.github.com/de/repositories/archiving-a-github-repository/referencing-and-citing-content) (document object identifier) from Zenodo only works with repositories.\n\nYou can, however, include a bibitem in the description of your gist (see the [\ud83d\udcdd Template](https://github.com/laurenzbeck/gists?tab=readme-ov-file#-template)):\n\n```bibtex\n@misc{<bibkey>,\n author={<your name>},\n title={<the title of your gist>},\n year={<year of publication>},\n url={https://gist.github.com/<user name>/<gist id>},\n} \n```\n\n### \ud83d\udcdd Template\n\n#### Description\n\n````markdown\n# Title\n\n> \ud83d\udeae feel free to delete any section that is not helpful for your description (including this message).\n\nShort description.\n\n## \ud83d\udce6 Usage\n\nHow to use the gist with code examples.\n\n## \ud83e\udd14 Statement of Need\n\nDescribe why the code in your gist is needed.\n\n## \ud83d\udc0d Installation\n\nThis gist can be installed using the [`python-gists-import`]() package:\n\n```sh\n$pip install python-gists-import\n``` \n\nAfter that, simply import the gist in your code via:\n\n```python\nfrom gists import <gist id>\n```\n\n### \ud83d\udcc4 Requirements\n\nIf your gist depends on other Python packages, include a list of those dependencies here. Users have to manually make sure that they have these dependencies installed. I would suggest using version specifiers used by [poetry](https://python-poetry.org/docs/dependency-specification/):\n\n```toml\npython = \"^3.11\"\n```\n\n## \ud83d\udddd\ufe0f License and Copyright \u00a9\ufe0f\n\nThe code inside this gist is licensed under the [MIT](https://opensource.org/license/mit) license.\n\nCopyright <YEAR> <COPYRIGHT HOLDER>\n\n## \ud83d\udcdd Cite Me\n\n```bibtex\n@misc{<bibkey>,\n author={<your name>},\n title={<the title of your gist>},\n year={<year of publication>},\n url={https://gist.github.com/<user name>/<gist id>},\n}\n```\n\n````\n\n#### Code\n\n```python\n\"\"\"# module title\n\nmodule description.\n\"\"\"\n# Copyright <YEAR> <COPYRIGHT HOLDER>\n#\n# Licensed under the [MIT](https://opensource.org/license/mit) license.\n\ndef hello(name: str = \"world\") -> None:\n \"\"\"\ud83d\udde3\ufe0f says hello to `name`.\"\"\"\n print(f\"hello, {name}!\")\n```\n\n---\n\n## \ud83d\uddbc\ufe0f \u00a9\ufe0f Banner Artwork Attribution\n\n<a rel=\"license\" href=\"http://creativecommons.org/licenses/by-nc-nd/3.0/\"><img alt=\"Creative Commons License\" style=\"border-width:0\" src=\"https://i.creativecommons.org/l/by-nc-nd/3.0/88x31.png\" /></a><br />The art in the banner of this README is licensed under a [Creative Commons Attribution-NonCommercial-No Derivatives Works 3.0 License](https://creativecommons.org/licenses/by-nc-nd/3.0/). It was made by [sephiroth-art](https://www.deviantart.com/sephiroth-art). Check out his beautiful artwork \u2764\ufe0f\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "\ud83d\udc0d\ud83d\udce6 this Python package provides a very convenient way to import GitHub gists in a pythonic way using `import` statements. ",
"version": "1.0.2",
"project_urls": {
"Homepage": "https://github.com/LaurenzBeck/gists.git",
"Repository": "https://github.com/LaurenzBeck/gists.git"
},
"split_keywords": [
"python",
" github",
" gists",
" import",
" deployment",
" \ud83d\udc0d",
" \ud83d\udce6"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "637ef15ea388fdbbec0fb0667254092115cf047c88c49080917279d451d62747",
"md5": "7a9ef568e6394b4e5fcbbdac18910777",
"sha256": "36c60c4373b33cc5cbe79c9239d10d6a23ea45c9862139fbbd9af3525e98b19f"
},
"downloads": -1,
"filename": "python_gists_import-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7a9ef568e6394b4e5fcbbdac18910777",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 6840,
"upload_time": "2024-07-03T07:34:16",
"upload_time_iso_8601": "2024-07-03T07:34:16.774228Z",
"url": "https://files.pythonhosted.org/packages/63/7e/f15ea388fdbbec0fb0667254092115cf047c88c49080917279d451d62747/python_gists_import-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2929af49adb338daf716030ec32e54eebe250c804546532829c5b334d18423d3",
"md5": "e0e2d351b6894c6d9ef3ec2cf792eb2b",
"sha256": "6335f035d37b8ce39b185bac25ee30fc0e617a421cd0655bcbd32f4f4552c185"
},
"downloads": -1,
"filename": "python_gists_import-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "e0e2d351b6894c6d9ef3ec2cf792eb2b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 7130,
"upload_time": "2024-07-03T07:34:18",
"upload_time_iso_8601": "2024-07-03T07:34:18.573081Z",
"url": "https://files.pythonhosted.org/packages/29/29/af49adb338daf716030ec32e54eebe250c804546532829c5b334d18423d3/python_gists_import-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-03 07:34:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "LaurenzBeck",
"github_project": "gists",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "python-gists-import"
}
JSON
