{
    "info": {
        "author": "Nicholas A. Lourie",
        "author_email": "developer.nick@kozbox.com",
        "bugtrack_url": null,
        "classifiers": [
            "License :: OSI Approved :: MIT License",
            "Operating System :: OS Independent",
            "Programming Language :: Python",
            "Programming Language :: Python :: 2.7"
        ],
        "description": "charitycheck\n============\n\na small module for verifying an organization's ability to accept\ncharitable contributions in the U.S. via their EIN number.\n\nvisit the `github <https://github.com/nalourie/charitycheck/>`__.\n\ninstallation\n============\n\nbasic installation\n------------------\n\n::\n\n    pip install charitycheck\n\nsimple as that, you're now good to go! But make sure to read on for\n(very important) notices about module useage and getting good\nperformance.\n\nDisclaimer About and Maintaining Up-to-date Information\n-------------------------------------------------------\n\nReturned charity status may not be up-to-date\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThis module uses the IRS publication 78 to perform its checks against\ncharity EIN's. Essentially, the module downloads a copy of IRS Pub 78,\nunzips the file, converts the data to a quickly searchable dbm file, and\nthen provides some functions to interface with this file. That means\nthat the module searches its local version of Publication 78, thus if\nyou check for a new nonprofit's charity status, it might not yet be in\nyour database. Similarly, if a nonprofit recently lost its status, your\ndatabase might not yet reflect that either.\n\nHow to update your charity information\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nTo fix the above problem, you should regularly update your dbm file.\nThis can be done by running this module as a script from the\ncommandline:\n\n::\n\n    python /path/to/charitycheck.py\n\n(in the above command, python should be whatever command your system\nuses to run python scripts, of course)\n\nor importing the function ``make_dbm`` and running it without arguments:\n\n.. code:: python\n\n    from charitycheck import make_dbm\n\n    make_dbm()\n\nSo that you don't forget to do this regularly, we recommend setting up a\ncron job to do this at least less than every two weeks (14 days). You\nmust be the judge of how important it is to make the most up to date\ninformation on these nonprofit organizations available to your module.\n\nAuto updating and performance\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nBecause having up-to-date information from the IRS is so important,\nwe've added a way for python to internally track how up-to-date your\ncopy of publication 78 is. If you're local copy is 15 or more days out\nof date, then the module will automatically download a new copy and\nrecreate the database when one of the public functions in it is called\nwith the argument ``optimize=False``, which they are all set to by\ndefault; however, creating the database can take up to several minutes,\nso *not regularly updating your database will unpredictably and severely\naffect the performance of this module, on top of increasingly jeopardize\nthe validity of its results*.\n\nOnly you can decide how often you should update your database, but for\nthis reason we suggest at least once every 14 days.\n\nNote on performance:\n--------------------\n\nThe module uses python's anydbm module, so for performance reasons you\nshould make sure that you have a fast implementation of the dbm format\ninstalled to which python has access. Simply try the following imports\nto check:\n\n.. code:: python\n\n    import dbm # the classic new dbm implementation\n\n.. code:: python\n\n    import gdbm # gnu dbm implementation\n\n.. code:: python\n\n    import dbhash # dbm implementation found on windows in python2.7\n\nIf any of these imports work, you're good to go. If none of them work,\nthis module will still operate for you, but it will use the ``dumbdbm``\nimplementation, and could be much slower. Consider getting one of the\nabove dbm implementations in python (dbhash is also deprecated and not\nincluded in python 3).\n\nbasic useage\n============\n\nThe following are the public functions make available by the module:\n\n.. code:: python\n\n    make_dbm()\n\nDownloads publication 78 from the IRS, unzips it, saves the txt to disk,\nthen converts it into a dbm file for quick useage.\n\n.. code:: python\n\n    get_nonprofit_data(\n        ein, # the nonprofit organization's ein number\n        optimize=False)\n\nGiven an EIN, retrieves the pipe delimited string data,\n``\"name|city|state|country|deductability code\"`` from the local copy of\npublication 78 if the organization exists, otherwise it raises a key\nerror.\n\nIf ``optimize=False``, as by default, then it also checks to make sure\nthe local copy of publication 78 is no more than 15 days out of date,\ncalling ``make_dbm()`` if the data is more out of date than 15 days.\n\n.. code:: python\n\n    verify_nonprofit(\n        ein, # the nonprofit organization's ein number\n        name=None, # name of the organization **as it appears in publication 78**\n        city=None, # name of the city the organization is based in\n        state=None, # state abbreviation for the organization\n        deductability_code=None, # the deductability code of the organization\n            # (see 'explanation of data and sources' in README.md)\n        optimize=False)\n\ntakes data about the nonprofit organization as outlined in its call\nsignature. The EIN must always be provided, all data should be given as\nstrings. Every piece of information provided besides the EIN is\noptional. The function will take the provided non-None data, and check\nit against organizations in the database. If an organization is found\nmatching the provided arguments, then ``verify_nonprofit`` returns true,\nelse it returns false. The optimize parameter behaves the same as in\n``get_nonprofit_data``.\n\n.. code:: python\n\n    get_deductability_code(\n        ein, # the nonprofit organization's ein number\n        name=None, # name of the organization **as it appears in publication 78**\n        city=None, # name of the city the organization is based in\n        state=None, # state abbreviation for the organization\n        optimize=False)\n\ntakes data about the nonprofit organization as outlined in its call\nsignature, the same as with ``verify_nonprofit`` except that it doesn't\naccept a deductability code argument. Checks the provided data against\norganizations in the database, if a match is found, it returns the\ndeductability code, if no match is found, it returns the empty string.\nThe optimize parameter behaves the same as the optimize parameter for\n``get_nonprofit_data``.\n\nOf course, this function can also be used to replace\n``verify_nonprofit`` in a more extensible way, by coercing the string\nvalues returned by ``get_deductability_code`` to booleans.\n\nexplanation of data and sources\n===============================\n\nThe data used in this module is generated from IRS publication 78,\nlocated at http://apps.irs.gov/app/eos/forwardToPub78Download.do.\n\nThe format of the file at that download site is expected to be a zipped\nfolder, containing a text file, whose names are both\ndata-download-pub78.zip and data-download-pub78.txt respectively, with\ndata-download-pub78.txt being a textfile with a charity on each line,\nand every line having the format:\n\n::\n\n    EIN|name|city|state|country|deductability code\n\nIf any of these assumptions change, the code may need to change\naccordingly\n\nFrom the IRS website, here is an explanation of the deductability status\ncodes:\n\n::\n\n    -----------------------------------------------------------------------------------------------\n    | Code    |    Type of organization and use of contribution.    |    Deductibility Limitation |\n    -----------------------------------------------------------------------------------------------\n    | PC      |    A public charity.                                |    50%                      |\n    -----------------------------------------------------------------------------------------------\n    | POF     |    A private operating foundation.                  |    50%                      |\n    -----------------------------------------------------------------------------------------------             \n    | PF      |    A private foundation.                            |    30% (generally)          |\n    ----------------------------------------------------------------------------------------------- \n    | GROUP   |    Generally, a central organization holding a group|                             |\n    |         |    exemption letter, whose subordinate units covered|                             |\n    |         |    by the group exemption are also eligible to      | Depends on various factors. |\n    |         |    receive tax-deductible contributions, even though|                             |\n    |         |    they are not separately listed.                  |                             |\n    -----------------------------------------------------------------------------------------------\n    | LODGE   |    A domestic fraternal society, operating under the|                             |\n    |         |    lodge system, but only if the contribution is to |    30%                      |\n    |         |    be used exclusively for charitable purposes.     |                             |\n    -----------------------------------------------------------------------------------------------\n    | UNKWN   |    A charitable organization whose public charity   | Depends on various factors. |\n    |         |    status has not been determined.                  |                             |\n    -----------------------------------------------------------------------------------------------\n    | EO      |    An organization described in section 170(c) of   |                             |\n    |         |    the Internal Revenue Code other than a public    | Depends on various factors. |\n    |         |    charity or private foundation.                   |                             |\n    -----------------------------------------------------------------------------------------------\n    | FORGN   |    A foreign-addressed organization. These are      |                             | \n    |         |    generally organizations formed in the United     |                             | \n    |         |    States that conduct activities in foreign        |                             | \n    |         |    countries. Certain foreign organizations that    | Depends on various factors. |\n    |         |    receive charitable contributions deductible      |                             | \n    |         |    pursuant to treaty are also included, as are     |                             | \n    |         |    organizations created in U.S. possessions.       |                             | \n    -----------------------------------------------------------------------------------------------\n    | SO      |    A Type I, Type II, or functionally integrated    |    50%                      |\n    |         |    Type III supporting organization.                |                             |\n    -----------------------------------------------------------------------------------------------\n    | SONFI   |    A non-functionally integrated Type III           |    50%                      |\n    |         |    supporting organization.                         |                             |\n    -----------------------------------------------------------------------------------------------\n    | SOUNK   |    A supporting organization, unspecified type.     |    50%                      |\n    -----------------------------------------------------------------------------------------------\n\n    # contributors\n\n    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!",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "UNKNOWN",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/nalourie/charitycheck",
        "keywords": "nonprofit nonprofits EIN IRS verify",
        "license": "MIT License",
        "maintainer": null,
        "maintainer_email": null,
        "name": "charitycheck",
        "package_url": "https://pypi.org/project/charitycheck/",
        "platform": "UNKNOWN",
        "project_url": "https://pypi.org/project/charitycheck/",
        "project_urls": {
            "Download": "UNKNOWN",
            "Homepage": "https://github.com/nalourie/charitycheck"
        },
        "release_url": "https://pypi.org/project/charitycheck/1.1/",
        "requires_dist": null,
        "requires_python": null,
        "summary": "a small module to verify informationabout nonprofits using their EINs",
        "version": "1.1"
    },
    "last_serial": 1276094,
    "releases": {
        "1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "2a8112c822ba3de6fcef2d362587eb6d",
                    "sha256": "710324503f6504a66e26296794df25f4ea7194e07d6fa8f94fd794599449c237"
                },
                "downloads": -1,
                "filename": "charitycheck-1.0.zip",
                "has_sig": false,
                "md5_digest": "2a8112c822ba3de6fcef2d362587eb6d",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 15455,
                "upload_time": "2014-09-08T21:38:25",
                "url": "https://files.pythonhosted.org/packages/41/17/f2fb1c8beb60bd788c45b2fe4774832627af1f85ee55d1bdfbd0115284ce/charitycheck-1.0.zip"
            }
        ],
        "1.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "193f42ecc673bd1bb436cb44ebbda14f",
                    "sha256": "b5156a7ed82f1198eba672fca0696cf87cd070c632de386eeb9466b8ff47e7a0"
                },
                "downloads": -1,
                "filename": "charitycheck-1.1.zip",
                "has_sig": false,
                "md5_digest": "193f42ecc673bd1bb436cb44ebbda14f",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 19618,
                "upload_time": "2014-10-20T05:01:18",
                "url": "https://files.pythonhosted.org/packages/48/f4/8a0fc6fe188d91e869ade89684a8cae83ba60d2074b339b4390e2c286ddf/charitycheck-1.1.zip"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "193f42ecc673bd1bb436cb44ebbda14f",
                "sha256": "b5156a7ed82f1198eba672fca0696cf87cd070c632de386eeb9466b8ff47e7a0"
            },
            "downloads": -1,
            "filename": "charitycheck-1.1.zip",
            "has_sig": false,
            "md5_digest": "193f42ecc673bd1bb436cb44ebbda14f",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 19618,
            "upload_time": "2014-10-20T05:01:18",
            "url": "https://files.pythonhosted.org/packages/48/f4/8a0fc6fe188d91e869ade89684a8cae83ba60d2074b339b4390e2c286ddf/charitycheck-1.1.zip"
        }
    ]
}