# Python This guide describes how to use Nightfall with the Python programming language. The example below will demonstrate how to use Nightfall’s text scanning functionality to verify whether a string contains sensitive PII using the Nightfall Python SDK. To request the Nightfall API you will need: * A Nightfall API key * An existing Nightfall Detection Rule * Data to scan. Note that the API interprets data as plaintext, so you may pass it in any structured or unstructured format. You can read more about [obtaining a Nightfall API key](https://developer.nightfall.ai/reference#creating-your-first-api-key) or about our [available data detectors](https://help.nightfall.ai/detection/nightfalls-detector-library/detectors) in the linked reference guides. In this tutorial, we will be downloading, setting up, and using the Python SDK provided by Nightfall. We recommend you first set up a virtual environment. You can learn more about that [here](https://docs.python.org/3/library/venv.html). You can download the Nightfall SDK from PyPi like this: We will be using the built-in `os` library to help run this sample API script. This will be used to help extract the API Key from the OS as an environment variable. ```python import os from nightfall import Confidence, DetectionRule, Detector, LogicalOp, Nightfall ``` Next, we extract our API Key, and abstract a nightfall class from the SDK, for it. In this example, we have our API key set via an environment variable called `NIGHTFALL_API_KEY`. Your API key should **never** be hard-coded directly into your script. ```python nightfall = Nightfall(os.environ['NIGHTFALL_API_KEY']) ``` Next we define the Detection Rule with which we wish to scan our data. The Detection Rule can be [pre-made in the Nightfall web app](https://app.nightfall.ai/policy-engine/policies) and referenced by UUID. ```python detection_rule_uuid = os.environ.get('DETECTION_RULE_UUID') ``` In this example, we will use some example data in the `payload` List. > ### 🚧Payload Limit > > Payloads must be under 500 KB when using the Scan API. If your file is larger than the limit, consider using the file api, which is also available via the Python SDK. We will ignore the second parameter as we do not have redaction configured for this request. With the Nightfall API, you can redact and mask your findings. You can add a Redaction Config, as part of your Detection Rule. For more information on how to use redaction, and its specific options, please refer to the guide here. {% tabs %} {% tab title="Using Detection Rule UUIDs" %} ```python payload = [ "The customer social security number is 458-02-6124", "No PII in this string", "My credit card number is 4916-6734-7572-5015" ] result, _ = nightfall.scan_text( payload, detection_rule_uuids=[detection_rule_uuid] ) ``` {% endtab %} {% tab title="Using Detection Rules Inline" %} ```python payload = [ "The customer social security number is 458-02-6124", "No PII in this string", "My credit card number is 4916-6734-7572-5015" ] result, _ = nightfall.scan_text( payload, detection_rules=[ DetectionRule( name="Sample_Detection_Rule", logical_op=LogicalOp.ANY, detectors=[ Detector( min_confidence=Confidence.VERY_LIKELY, min_num_findings=1, display_name="Credit Card", nightfall_detector="CREDIT_CARD_NUMBER", ), Detector( min_confidence=Confidence.VERY_LIKELY, min_num_findings=1, display_name="Social", nightfall_detector="US_SOCIAL_SECURITY_NUMBER", ) ] ) ] ) ``` {% endtab %} {% endtabs %} ## Reviewing Results Now we are ready to review the results from the Nightfall SDK to check if there is any sensitive data in our file. Since the results will be in a [dataclass](https://docs.python.org/3/library/dataclasses.html), we can use the built-in `__repr__` functions to format the results in a user-friendly and readable manner. All data and sample findings shown below are validated, non-sensitive, examples of sample data. If there are no sensitive findings in our payload, the response will be as shown in the 'empty response' pane below: {% tabs %} {% tab title="Positive Response - Using Detection Rule UUID" %} ```python [ [Finding(finding='458-02-6124', redacted_finding=None, before_context=None, after_context=None, detector_name='US social security number (SSN)', detector_uuid='e30d9a87-f6c7-46b9-a8f4-16547901e069', confidence=, byte_range=Range(start=39, end=50), codepoint_range=Range(start=39, end=50), matched_detection_rule_uuids=['c67e3dd7-560e-438f-8c72-6ec54979396f'], matched_detection_rules=[])], [], [Finding(finding='4916-6734-7572-5015', redacted_finding=None, before_context=None, after_context=None, detector_name='Credit card number', detector_uuid='74c1815e-c0c3-4df5-8b1e-6cf98864a454', confidence=, byte_range=Range(start=25, end=44), codepoint_range=Range(start=25, end=44), matched_detection_rule_uuids=['c67e3dd7-560e-438f-8c72-6ec54979396f'], matched_detection_rules=[])] ] ``` {% endtab %} {% tab title="Positive Response - Using Detection Rules Inline" %} ```python [ [Finding(finding='458-02-6124', redacted_finding=None, before_context=None, after_context=None, detector_name='Social', detector_uuid='e30d9a87-f6c7-46b9-a8f4-16547901e069', confidence=, byte_range=Range(start=39, end=50), codepoint_range=Range(start=39, end=50), matched_detection_rule_uuids=[], matched_detection_rules=['Sample_Detection_Rule'])], [], [Finding(finding='4916-6734-7572-5015', redacted_finding=None, before_context=None, after_context=None, detector_name='Credit Card', detector_uuid='74c1815e-c0c3-4df5-8b1e-6cf98864a454', confidence=, byte_range=Range(start=25, end=44), codepoint_range=Range(start=25, end=44), matched_detection_rule_uuids=[], matched_detection_rules=['Sample_Detection_Rule'])], ] ``` {% endtab %} {% tab title="Empty Response" %} ```python [[], [], []] ``` {% endtab %} {% endtabs %} And that's it :tada: You are now ready to use the Python SDK for other scenarios. *** --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.nightfall.ai/developer-api/language_specific_guides/python.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.