Metadata-Version: 2.4
Name: faker-credit-score
Version: 1.0.0
Summary: Generate realistic fake credit scores (FICO 8, VantageScore, etc.) for testing fintech, lending, and insurance applications. A Faker provider with tier-based generation and 10 scoring models.
Project-URL: Homepage, https://github.com/crd/faker-credit-score
Project-URL: Repository, https://github.com/crd/faker-credit-score
Author: Cory Donnelly
License: BSD 3-Clause License
        
        Copyright (c) 2018, Cory Donnelly
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        * Redistributions of source code must retain the above copyright notice, this
          list of conditions and the following disclaimer.
        
        * Redistributions in binary form must reproduce the above copyright notice,
          this list of conditions and the following disclaimer in the documentation
          and/or other materials provided with the distribution.
        
        * Neither the name of the copyright holder nor the names of its
          contributors may be used to endorse or promote products derived from
          this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Keywords: credit-score,faker,fico,fintech,lending,mock-data,test-data,vantagescore
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: faker>=37.8.0
Description-Content-Type: text/x-rst

faker_credit_score
==================

*Stop hardcoding 720 in your tests.*

|pypi| |status| |coverage| |license|

A `Faker`_ provider that generates realistic credit scores across 10 industry
scoring models -- FICO 8, VantageScore, Equifax Beacon, and more. Constrain by
tier, get real bureau names, and test the paths that actually matter.

Why this exists
---------------

Hardcoding ``credit_score = 720`` in your fixtures doesn't test anything. You
don't know if that's "good" for FICO 8 or "fair" for Equifax Beacon 5.0 and
``random.randint(300, 850)`` gives you numbers that don't map to any real model.

If you're building a lending flow, an insurance quote engine, or anything that
branches on creditworthiness you need scores that come from the right ranges,
tied to real bureau names, with accurate tiering.

**Before:**

.. code:: python

    # What does 720 even test? Which model? Which tier?
    user["credit_score"] = 720

**After:**

.. code:: python

    fake.credit_score(tier="poor")           # 542 -- test the denial path
    fake.credit_score(tier="exceptional")    # 831 -- test the approval path

    result = fake.credit_score_full("fico5")
    # CreditScoreResult(name='Equifax Beacon 5.0', provider='Equifax', score=687)

Features
--------

- 10 of the most commonly-used scoring models (FICO 8/9/10, VantageScore 3.0/4.0, and more)
- Tier-based generation: ``poor``, ``fair``, ``good``, ``very_good``, ``exceptional``
- Score classification
- Structured results via ``CreditScoreResult`` namedtuple
- Works with the Faker CLI
- 100% test coverage

Installation
------------

.. code:: bash

    pip install faker-credit-score

Two lines to add it to your existing Faker setup:

.. code:: python

    from faker import Faker
    from faker_credit_score import CreditScore

    fake = Faker()
    fake.add_provider(CreditScore)

Usage
-----

Generate Scores
~~~~~~~~~~~~~~~

.. code:: python

    fake.credit_score()
    # 791

    fake.credit_score("fico5")
    # 687

    fake.credit_score_name()
    # 'TransUnion FICO Risk Score, Classic 04'

    fake.credit_score_provider()
    # 'TransUnion'

Full Credit Score Result
~~~~~~~~~~~~~~~~~~~~~~~~

Returns a ``CreditScoreResult`` namedtuple with ``name``, ``provider``, and
``score`` fields:

.. code:: python

    fake.credit_score_full()
    # CreditScoreResult(name='FICO Score 8', provider='Equifax', score=791)

    name, provider, score = fake.credit_score_full("fico5")

Also works from the command line:

.. code:: bash

    $ faker credit_score -i faker_credit_score
    756

    $ faker credit_score_full -i faker_credit_score
    Equifax Beacon 5.0
    Equifax
    687

Credit Score Tiers
~~~~~~~~~~~~~~~~~~

Generate scores constrained to a tier, or classify existing scores:

.. code:: python

    fake.credit_score(tier="poor")
    # 542

    fake.credit_score(tier="exceptional")
    # 831

    fake.credit_score_tier()
    # 'good'

    fake.credit_score_tier(score=720)
    # 'good'

+---------------+-----------+
| Tier          | Range     |
+===============+===========+
| poor          | 300 - 579 |
+---------------+-----------+
| fair          | 580 - 669 |
+---------------+-----------+
| good          | 670 - 739 |
+---------------+-----------+
| very_good     | 740 - 799 |
+---------------+-----------+
| exceptional   | 800 - 850 |
+---------------+-----------+

Supported Models
~~~~~~~~~~~~~~~~

* FICO Score 8, 9, 10, 10 T
* VantageScore 3.0, 4.0
* UltraFICO
* Equifax Beacon 5.0
* Experian/Fair Isaac Risk Model V2SM
* TransUnion FICO Risk Score, Classic 04

Contributing
------------

Contributions are welcome, including from first-time open source contributors.
See `CONTRIBUTING.md <CONTRIBUTING.md>`_ for setup instructions and ideas.

License
-------

BSD 3-Clause. See `LICENSE <LICENSE>`_ for details.

.. |pypi| image:: https://img.shields.io/pypi/v/faker-credit-score.svg?style=flat-square
   :target: https://pypi.org/project/faker-credit-score/
   :alt: Latest version released on PyPI

.. |status| image:: https://github.com/crd/faker_credit_score/actions/workflows/test.yml/badge.svg?style=flat-square
   :target: https://github.com/crd/faker_credit_score/actions/workflows/test.yml
   :alt: Test workflow status

.. |coverage| image:: https://coveralls.io/repos/github/crd/faker_credit_score/badge.svg?branch=develop&style=flat-square
    :target: https://coveralls.io/github/crd/faker_credit_score?branch=develop
    :alt: Test coverage

.. |license| image:: https://img.shields.io/badge/License-BSD%203--Clause-blue.svg?style=flat-square
    :target: https://github.com/crd/faker_credit_score/blob/main/LICENSE
    :alt: BSD 3-Clause License

.. _Faker: https://github.com/joke2k/faker
