Package: charitycheck
charitychecka small module for verifying an organization’s ability to accept
charitable contributions in the U.S. via their EIN number.visit thegithub.installationbasic installationpip install charitychecksimple as that, you’re now good to go! But make sure to read on for
(very important) notices about module useage and getting good
performance.Disclaimer About and Maintaining Up-to-date InformationReturned charity status may not be up-to-dateThis module uses the IRS publication 78 to perform its checks against
charity EIN’s. Essentially, the module downloads a copy of IRS Pub 78,
unzips the file, converts the data to a quickly searchable dbm file, and
then provides some functions to interface with this file. That means
that the module searches its local version of Publication 78, thus if
you check for a new nonprofit’s charity status, it might not yet be in
your database. Similarly, if a nonprofit recently lost its status, your
database might not yet reflect that either.How to update your charity informationTo fix the above problem, you should regularly update your dbm file.
This can be done by running this module as a script from the
commandline:python /path/to/charitycheck.py(in the above command, python should be whatever command your system
uses to run python scripts, of course)or importing the functionmake_dbmand running it without arguments:fromcharitycheckimportmake_dbmmake_dbm()So that you don’t forget to do this regularly, we recommend setting up a
cron job to do this at least less than every two weeks (14 days). You
must be the judge of how important it is to make the most up to date
information on these nonprofit organizations available to your module.Auto updating and performanceBecause having up-to-date information from the IRS is so important,
we’ve added a way for python to internally track how up-to-date your
copy of publication 78 is. If you’re local copy is 15 or more days out
of date, then the module will automatically download a new copy and
recreate the database when one of the public functions in it is called
with the argumentoptimize=False, which they are all set to by
default; however, creating the database can take up to several minutes,
sonot regularly updating your database will unpredictably and severely
affect the performance of this module, on top of increasingly jeopardize
the validity of its results.Only you can decide how often you should update your database, but for
this reason we suggest at least once every 14 days.Note on performance:The module uses python’s anydbm module, so for performance reasons you
should make sure that you have a fast implementation of the dbm format
installed to which python has access. Simply try the following imports
to check:importdbm# the classic new dbm implementationimportgdbm# gnu dbm implementationimportdbhash# dbm implementation found on windows in python2.7If any of these imports work, you’re good to go. If none of them work,
this module will still operate for you, but it will use thedumbdbmimplementation, and could be much slower. Consider getting one of the
above dbm implementations in python (dbhash is also deprecated and not
included in python 3).basic useageThe following are the public functions make available by the module:make_dbm()Downloads publication 78 from the IRS, unzips it, saves the txt to disk,
then converts it into a dbm file for quick useage.get_nonprofit_data(ein,# the nonprofit organization's ein numberoptimize=False)Given an EIN, retrieves the pipe delimited string data,"name|city|state|country|deductability code"from the local copy of
publication 78 if the organization exists, otherwise it raises a key
error.Ifoptimize=False, as by default, then it also checks to make sure
the local copy of publication 78 is no more than 15 days out of date,
callingmake_dbm()if the data is more out of date than 15 days.verify_nonprofit(ein,# the nonprofit organization's ein numbername=None,# name of the organization **as it appears in publication 78**city=None,# name of the city the organization is based instate=None,# state abbreviation for the organizationdeductability_code=None,# the deductability code of the organization# (see 'explanation of data and sources' in README.md)optimize=False)takes data about the nonprofit organization as outlined in its call
signature. The EIN must always be provided, all data should be given as
strings. Every piece of information provided besides the EIN is
optional. The function will take the provided non-None data, and check
it against organizations in the database. If an organization is found
matching the provided arguments, thenverify_nonprofitreturns true,
else it returns false. The optimize parameter behaves the same as inget_nonprofit_data.get_deductability_code(ein,# the nonprofit organization's ein numbername=None,# name of the organization **as it appears in publication 78**city=None,# name of the city the organization is based instate=None,# state abbreviation for the organizationoptimize=False)takes data about the nonprofit organization as outlined in its call
signature, the same as withverify_nonprofitexcept that it doesn’t
accept a deductability code argument. Checks the provided data against
organizations in the database, if a match is found, it returns the
deductability code, if no match is found, it returns the empty string.
The optimize parameter behaves the same as the optimize parameter forget_nonprofit_data.Of course, this function can also be used to replaceverify_nonprofitin a more extensible way, by coercing the string
values returned byget_deductability_codeto booleans.explanation of data and sourcesThe data used in this module is generated from IRS publication 78,
located athttp://apps.irs.gov/app/eos/forwardToPub78Download.do.The format of the file at that download site is expected to be a zipped
folder, containing a text file, whose names are both
data-download-pub78.zip and data-download-pub78.txt respectively, with
data-download-pub78.txt being a textfile with a charity on each line,
and every line having the format:EIN|name|city|state|country|deductability codeIf any of these assumptions change, the code may need to change
accordinglyFrom the IRS website, here is an explanation of the deductability status
codes:-----------------------------------------------------------------------------------------------
| Code    |    Type of organization and use of contribution.    |    Deductibility Limitation |
-----------------------------------------------------------------------------------------------
| PC      |    A public charity.                                |    50%                      |
-----------------------------------------------------------------------------------------------
| POF     |    A private operating foundation.                  |    50%                      |
-----------------------------------------------------------------------------------------------
| PF      |    A private foundation.                            |    30% (generally)          |
-----------------------------------------------------------------------------------------------
| GROUP   |    Generally, a central organization holding a group|                             |
|         |    exemption letter, whose subordinate units covered|                             |
|         |    by the group exemption are also eligible to      | Depends on various factors. |
|         |    receive tax-deductible contributions, even though|                             |
|         |    they are not separately listed.                  |                             |
-----------------------------------------------------------------------------------------------
| LODGE   |    A domestic fraternal society, operating under the|                             |
|         |    lodge system, but only if the contribution is to |    30%                      |
|         |    be used exclusively for charitable purposes.     |                             |
-----------------------------------------------------------------------------------------------
| UNKWN   |    A charitable organization whose public charity   | Depends on various factors. |
|         |    status has not been determined.                  |                             |
-----------------------------------------------------------------------------------------------
| EO      |    An organization described in section 170(c) of   |                             |
|         |    the Internal Revenue Code other than a public    | Depends on various factors. |
|         |    charity or private foundation.                   |                             |
-----------------------------------------------------------------------------------------------
| FORGN   |    A foreign-addressed organization. These are      |                             |
|         |    generally organizations formed in the United     |                             |
|         |    States that conduct activities in foreign        |                             |
|         |    countries. Certain foreign organizations that    | Depends on various factors. |
|         |    receive charitable contributions deductible      |                             |
|         |    pursuant to treaty are also included, as are     |                             |
|         |    organizations created in U.S. possessions.       |                             |
-----------------------------------------------------------------------------------------------
| SO      |    A Type I, Type II, or functionally integrated    |    50%                      |
|         |    Type III supporting organization.                |                             |
-----------------------------------------------------------------------------------------------
| SONFI   |    A non-functionally integrated Type III           |    50%                      |
|         |    supporting organization.                         |                             |
-----------------------------------------------------------------------------------------------
| SOUNK   |    A supporting organization, unspecified type.     |    50%                      |
-----------------------------------------------------------------------------------------------

# contributors

So far this module has been developed only by Nicholas Lourie, but if other people are interested in helping to extend it to a larger framework for dealing with nonprofit data, pull requests are welcome!