| Name | sopel-501c3 JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | 501(c)(3) nonprofit lookup plugin for Sopel IRC bots. Based on Publication 78 data. |
| upload_time | 2025-02-21 13:42:47 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <4,>=3.8 |
| license | EFL-2.0 |
| keywords |
sopel
plugin
bot
irc
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# sopel-501c3
501(c)(3) nonprofit lookup plugin for Sopel IRC bots.
Consumes Publication 78 data.
## ⚠️ Important Notice
**Use of this plugin WILL inflate your bot's database size.** It intentionally
uses local storage in lieu of making an HTTP call out to someone's API every
time a command is called.
Importing the whole list of Publication 78 entries into a mostly empty test
instance grew the default SQLite `.db` file to approximately 300 MB. At time of
writing, the list consisted of 1,330,000 items occupying ~94 MB in decompressed
`.txt` format as provided by the IRS. (The final database size also includes
several column indexes, some of which are currently unused.)
## Installing
Releases are hosted on PyPI, so after installing Sopel, all you need is `pip`:
```shell
$ pip install sopel-501c3
```
### Configuring
The easiest way to configure `sopel-501c3` is via Sopel's configuration
wizard—simply run `sopel-plugins configure 501c3` and enter the values for which
it prompts you.
Only one option is present in the interactive wizard at this time:
* `update_interval`: how often (in days) the plugin should redownload the
Publication 78 data file and merge the contents with its database
### First startup
The first time Sopel is run with this plugin enabled, the plugin will
immediately fetch the latest Publication 78 data and start populating its
database table. This is a **blocking** update, and the bot will not continue
with startup until the data import is finished. Finishing the initial data
import could take several minutes—or longer, depending on system performance.
If interrupted (e.g. by pressing <kbd>Ctrl</kbd>+<kbd>C</kbd>), the initial
import will resume the next time Sopel is started—still in a blocking mode.
Entries already added will be checked again; while re-checking entries is
somewhat faster than adding new ones, letting the initial data load complete in
a single go will ultimately require the smallest amount of wall time.
After the *full* initial import finishes once, subsequent updates are run in a
background thread.
## Using
`sopel-501c3` provides one command with two names:
* `.501c3`/`.npo`: If passed an EIN, looks up that EIN. Otherwise, looks for
nonprofits whose names contain the query as a substring and responds with up
to three of them.
Fuzzier search would be a desirable feature someday, but this initial
implementation doesn't attempt it.
Likewise, the ability to "page" past the first three search results would be
handy, but that's a project for the future (or perhaps an eager contributor).
## Uninstalling
If you wish to remove this plugin, but keep using the bot instance for other
tasks, it's recommended to ``DROP TABLE `501c3_npos`;`` after the plugin is
deactivated/deleted.
How to do this will depend on the database backend you're using. For Sopel's default SQLite backend, that would look like:
**⚠️ WARNING: Destructive command with no confirmation step!**
```bash
sqlite3 /path/to/.sopel/configname.db "DROP TABLE '501c3_npos';" "VACUUM;"
```
Replace `configname` with the name of your Sopel config. If you don't specify
one when starting your bot (no `-c` argument), the name is probably `default`.
This one-liner removes the `sopel-501c3` table with all of its data, and
compacts the database file. (**Note:** `VACUUM` [could
require](https://www.sqlite.org/lang_vacuum.html#how_vacuum_works) up to 2x the
original file size in temporary disk space.)
Run against the same test instance [mentioned earlier](#️-important-notice),
doing this reduced the `.db` file from ~300 MB back down to ~50 KB.
## Changelog
### 0.1.0
First release of `sopel-501c3`.
Raw data
{
"_id": null,
"home_page": null,
"name": "sopel-501c3",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.8",
"maintainer_email": null,
"keywords": "sopel, plugin, bot, irc",
"author": null,
"author_email": "dgw <dgw@technobabbl.es>",
"download_url": "https://files.pythonhosted.org/packages/9f/7e/354eb95ed735286b114839ad10ef5f6b0e3aaea4e4b84408768bd847c46e/sopel_501c3-0.1.0.tar.gz",
"platform": "Linux x86, x86-64",
"description": "# sopel-501c3\n\n501(c)(3) nonprofit lookup plugin for Sopel IRC bots.\n\nConsumes Publication 78 data.\n\n## \u26a0\ufe0f Important Notice\n\n**Use of this plugin WILL inflate your bot's database size.** It intentionally\nuses local storage in lieu of making an HTTP call out to someone's API every\ntime a command is called.\n\nImporting the whole list of Publication 78 entries into a mostly empty test\ninstance grew the default SQLite `.db` file to approximately 300 MB. At time of\nwriting, the list consisted of 1,330,000 items occupying ~94 MB in decompressed\n`.txt` format as provided by the IRS. (The final database size also includes\nseveral column indexes, some of which are currently unused.)\n\n## Installing\n\nReleases are hosted on PyPI, so after installing Sopel, all you need is `pip`:\n\n```shell\n$ pip install sopel-501c3\n```\n\n### Configuring\n\nThe easiest way to configure `sopel-501c3` is via Sopel's configuration\nwizard\u2014simply run `sopel-plugins configure 501c3` and enter the values for which\nit prompts you.\n\nOnly one option is present in the interactive wizard at this time:\n\n* `update_interval`: how often (in days) the plugin should redownload the\n Publication 78 data file and merge the contents with its database\n\n### First startup\n\nThe first time Sopel is run with this plugin enabled, the plugin will\nimmediately fetch the latest Publication 78 data and start populating its\ndatabase table. This is a **blocking** update, and the bot will not continue\nwith startup until the data import is finished. Finishing the initial data\nimport could take several minutes\u2014or longer, depending on system performance.\n\nIf interrupted (e.g. by pressing <kbd>Ctrl</kbd>+<kbd>C</kbd>), the initial\nimport will resume the next time Sopel is started\u2014still in a blocking mode.\nEntries already added will be checked again; while re-checking entries is\nsomewhat faster than adding new ones, letting the initial data load complete in\na single go will ultimately require the smallest amount of wall time.\n\nAfter the *full* initial import finishes once, subsequent updates are run in a\nbackground thread.\n\n## Using\n\n`sopel-501c3` provides one command with two names:\n\n* `.501c3`/`.npo`: If passed an EIN, looks up that EIN. Otherwise, looks for\n nonprofits whose names contain the query as a substring and responds with up\n to three of them.\n\nFuzzier search would be a desirable feature someday, but this initial\nimplementation doesn't attempt it.\n\nLikewise, the ability to \"page\" past the first three search results would be\nhandy, but that's a project for the future (or perhaps an eager contributor).\n\n## Uninstalling\n\nIf you wish to remove this plugin, but keep using the bot instance for other\ntasks, it's recommended to ``DROP TABLE `501c3_npos`;`` after the plugin is\ndeactivated/deleted.\n\nHow to do this will depend on the database backend you're using. For Sopel's default SQLite backend, that would look like:\n\n**\u26a0\ufe0f WARNING: Destructive command with no confirmation step!**\n\n```bash\nsqlite3 /path/to/.sopel/configname.db \"DROP TABLE '501c3_npos';\" \"VACUUM;\"\n```\n\nReplace `configname` with the name of your Sopel config. If you don't specify\none when starting your bot (no `-c` argument), the name is probably `default`.\n\nThis one-liner removes the `sopel-501c3` table with all of its data, and\ncompacts the database file. (**Note:** `VACUUM` [could\nrequire](https://www.sqlite.org/lang_vacuum.html#how_vacuum_works) up to 2x the\noriginal file size in temporary disk space.)\n\nRun against the same test instance [mentioned earlier](#\ufe0f-important-notice),\ndoing this reduced the `.db` file from ~300 MB back down to ~50 KB.\n\n## Changelog\n\n### 0.1.0\n\nFirst release of `sopel-501c3`.\n",
"bugtrack_url": null,
"license": "EFL-2.0",
"summary": "501(c)(3) nonprofit lookup plugin for Sopel IRC bots. Based on Publication 78 data.",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/dgw/sopel-501c3/issues",
"Homepage": "https://github.com/dgw/sopel-501c3"
},
"split_keywords": [
"sopel",
" plugin",
" bot",
" irc"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "59516220ef1dfe9768b8f19ec7ce5eaabe32845158a7bd31be1880bb5197afc2",
"md5": "d2664192865f568d510f98d1a8e5379a",
"sha256": "cf4819790e5ba8bdc2c0f18d663646611c7f27e56236b7e890c7290f8d9334b5"
},
"downloads": -1,
"filename": "sopel_501c3-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d2664192865f568d510f98d1a8e5379a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.8",
"size": 11202,
"upload_time": "2025-02-21T13:42:44",
"upload_time_iso_8601": "2025-02-21T13:42:44.149078Z",
"url": "https://files.pythonhosted.org/packages/59/51/6220ef1dfe9768b8f19ec7ce5eaabe32845158a7bd31be1880bb5197afc2/sopel_501c3-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9f7e354eb95ed735286b114839ad10ef5f6b0e3aaea4e4b84408768bd847c46e",
"md5": "5aeb5e2eeab9b5a2da430c3886504855",
"sha256": "00bab3b18d365724d495a7b348003315adedc8e426d8157e6271a96e25f7dd52"
},
"downloads": -1,
"filename": "sopel_501c3-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "5aeb5e2eeab9b5a2da430c3886504855",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.8",
"size": 11434,
"upload_time": "2025-02-21T13:42:47",
"upload_time_iso_8601": "2025-02-21T13:42:47.471789Z",
"url": "https://files.pythonhosted.org/packages/9f/7e/354eb95ed735286b114839ad10ef5f6b0e3aaea4e4b84408768bd847c46e/sopel_501c3-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-21 13:42:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dgw",
"github_project": "sopel-501c3",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sopel-501c3"
}
