<commit_before>"""REDCap API methods for Project records"""
from datetime import datetime

from typing import TYPE_CHECKING, Any, Dict, List, Literal, Optional, Union, overload

from redcap.methods.base import Base, EmptyJson, Json

if TYPE_CHECKING:
    import pandas as pd


class Records(Base):
    """Responsible for all API methods under 'Records' in the API Playground"""

    # pylint: disable=too-many-locals
    @overload
    def export_records(
        self,
        format_type: Literal["json"],
        records: Optional[List[str]] = None,
        fields: Optional[List[str]] = None,
        forms: Optional[List[str]] = None,
        events: Optional[List[str]] = None,
        raw_or_label: Literal["raw", "label", "both"] = "raw",
        raw_or_label_headers: Literal["raw", "label"] = "raw",
        event_name: Literal["label", "unique"] = "label",
        record_type: Literal["flat", "eav"] = "flat",
        export_survey_fields: bool = False,
        export_data_access_groups: bool = False,
        df_kwargs: Optional[Dict[str, Any]] = None,
        export_checkbox_labels: bool = False,
        filter_logic: Optional[str] = None,
        date_begin: Optional[datetime] = None,
        date_end: Optional[datetime] = None,
        decimal_character: Optional[Literal[",", "."]] = None,
        export_blank_for_gray_form_status: Optional[bool] = None,
    ) -> Json:
        ...

    @overload
    def export_records(
        self,
        format_type: Literal["csv", "xml"],
        records: Optional[List[str]] = None,
        fields: Optional[List[str]] = None,
        forms: Optional[List[str]] = None,
        events: Optional[List[str]] = None,
        raw_or_label: Literal["raw", "label", "both"] = "raw",
        raw_or_label_headers: Literal["raw", "label"] = "raw",
        event_name: Literal["label", "unique"] = "label",
        record_type: Literal["flat", "eav"] = "flat",
        export_survey_fields: bool = False,
        export_data_access_groups: bool = False,
        df_kwargs: Optional[Dict[str, Any]] = None,
        export_checkbox_labels: bool = False,
        filter_logic: Optional[str] = None,
        date_begin: Optional[datetime] = None,
        date_end: Optional[datetime] = None,
        decimal_character: Optional[Literal[",", "."]] = None,
        export_blank_for_gray_form_status: Optional[bool] = None,
    ) -> str:
        ...

    @overload
    def export_records(
        self,
        format_type: Literal["df"],
        records: Optional[List[str]] = None,
        fields: Optional[List[str]] = None,
        forms: Optional[List[str]] = None,
        events: Optional[List[str]] = None,
        raw_or_label: Literal["raw", "label", "both"] = "raw",
        raw_or_label_headers: Literal["raw", "label"] = "raw",
        event_name: Literal["label", "unique"] = "label",
        record_type: Literal["flat", "eav"] = "flat",
        export_survey_fields: bool = False,
        export_data_access_groups: bool = False,
        df_kwargs: Optional[Dict[str, Any]] = None,
        export_checkbox_labels: bool = False,
        filter_logic: Optional[str] = None,
        date_begin: Optional[datetime] = None,
        date_end: Optional[datetime] = None,
        decimal_character: Optional[Literal[",", "."]] = None,
        export_blank_for_gray_form_status: Optional[bool] = None,
    ) -> "pd.DataFrame":
        ...

    def export_records(
        self,
        format_type: Literal["json", "csv", "xml", "df"] = "json",
        records: Optional[List[str]] = None,
        fields: Optional[List[str]] = None,
        forms: Optional[List[str]] = None,
        events: Optional[List[str]] = None,
        raw_or_label: Literal["raw", "label", "both"] = "raw",
        raw_or_label_headers: Literal["raw", "label"] = "raw",
        event_name: Literal["label", "unique"] = "label",
        record_type: Literal["flat", "eav"] = "flat",
        export_survey_fields: bool = False,
        export_data_access_groups: bool = False,
        df_kwargs: Optional[Dict[str, Any]] = None,
        export_checkbox_labels: bool = False,
        filter_logic: Optional[str] = None,
        date_begin: Optional[datetime] = None,
        date_end: Optional[datetime] = None,
        decimal_character: Optional[Literal[",", "."]] = None,
        export_blank_for_gray_form_status: Optional[bool] = None,
    ):
        # pylint: disable=line-too-long
        """
        Export data from the REDCap project.

        Args:
            format_type:
                Format of returned data. `'json'` returns json-decoded
                objects while `'csv'` and `'xml'` return other formats.
                `'df'` will attempt to return a `pandas.DataFrame`
            records:
                Array of record names specifying specific records to export.
                By default, all records are exported
            fields:
                Array of field names specifying specific fields to pull
                by default, all fields are exported
            forms:
                Array of form names to export. If in the web UI, the form
                name has a space in it, replace the space with an underscore
                By default, all forms are exported
            events:
                An array of unique event names from which to export records
                Note:
                    This only applies to longitudinal projects
            raw_or_label:
                Export the raw coded values or labels for the options of
                multiple choice fields, or both
            raw_or_label_headers:
                Export the column names of the instrument as their raw
                value or their labeled value
            event_name:
                Export the unique event name or the event label
            record_type:
                Database output structure type
            export_survey_fields:
                Specifies whether or not to export the survey identifier
                field (e.g., "redcap_survey_identifier") or survey timestamp
                fields (e.g., form_name+"_timestamp") when surveys are
                utilized in the project
            export_data_access_groups:
                Specifies whether or not to export the
                `"redcap_data_access_group"` field when data access groups
                are utilized in the project

                Note:
                    This flag is only viable if the user whose token is
                    being used to make the API request is *not* in a data
                    access group. If the user is in a group, then this flag
                    will revert to its default value.
            df_kwargs:
                Passed to `pandas.read_csv` to control construction of
                returned DataFrame.
                By default, `{'index_col': self.def_field}`
            export_checkbox_labels:
                Specify whether to export checkbox values as their label on
                export.
            filter_logic:
                Filter which records are returned using REDCap conditional syntax
            date_begin:
                Filter on records created after a date
            date_end:
                Filter on records created before a date
            decimal_character:
                Force all numbers into same decimal format
            export_blank_for_gray_form_status:
                Whether or not to export blank values for instrument complete status fields
                that have a gray status icon
        Returns:
            Union[List[Dict[str, Any]], str, pd.DataFrame]: Exported data

        Examples:
            >>> proj.export_records()
            [{'record_id': '1', 'redcap_event_name': 'event_1_arm_1', 'redcap_repeat_instrument': '',
            'redcap_repeat_instance': 1, 'field_1': '1',
            'checkbox_field___1': '0', 'checkbox_field___2': '1', 'upload_field': 'test_upload.txt',
            'form_1_complete': '2'},
            {'record_id': '2', 'redcap_event_name': 'event_1_arm_1', 'redcap_repeat_instrument': '',
            'redcap_repeat_instance': 1, 'field_1': '0',
            'checkbox_field___1': '0', 'checkbox_field___2': '0', 'upload_field': 'myupload.txt',
            'form_1_complete': '0'}]

            >>> proj.export_records(filter_logic="[field_1] = 1")
            [{'record_id': '1', 'redcap_event_name': 'event_1_arm_1', 'redcap_repeat_instrument': '',
            'redcap_repeat_instance': 1, 'field_1': '1',
            'checkbox_field___1': '0', 'checkbox_field___2': '1', 'upload_field': 'test_upload.txt',
            'form_1_complete': '2'}]

            >>> proj.export_records(
            ...     format_type="csv",
            ...     fields=["field_1", "checkbox_field"],
            ...     raw_or_label="label"
            ... )
            'field_1,checkbox_field___1,checkbox_field___2\\nYes,Unchecked,Checked\\nNo,Unchecked,Unchecked\\n'
<commit_msg>:arrow_down: Move df_kwargs to end of arg list for export_records<commit_after>"""REDCap API methods for Project records"""
from datetime import datetime

from typing import TYPE_CHECKING, Any, Dict, List, Literal, Optional, Union, overload

from redcap.methods.base import Base, EmptyJson, Json

if TYPE_CHECKING:
    import pandas as pd


class Records(Base):
    """Responsible for all API methods under 'Records' in the API Playground"""

    # pylint: disable=too-many-locals
    @overload
    def export_records(
        self,
        format_type: Literal["json"],
        records: Optional[List[str]] = None,
        fields: Optional[List[str]] = None,
        forms: Optional[List[str]] = None,
        events: Optional[List[str]] = None,
        raw_or_label: Literal["raw", "label", "both"] = "raw",
        raw_or_label_headers: Literal["raw", "label"] = "raw",
        event_name: Literal["label", "unique"] = "label",
        record_type: Literal["flat", "eav"] = "flat",
        export_survey_fields: bool = False,
        export_data_access_groups: bool = False,
        export_checkbox_labels: bool = False,
        filter_logic: Optional[str] = None,
        date_begin: Optional[datetime] = None,
        date_end: Optional[datetime] = None,
        decimal_character: Optional[Literal[",", "."]] = None,
        export_blank_for_gray_form_status: Optional[bool] = None,
        df_kwargs: Optional[Dict[str, Any]] = None,
    ) -> Json:
        ...

    @overload
    def export_records(
        self,
        format_type: Literal["csv", "xml"],
        records: Optional[List[str]] = None,
        fields: Optional[List[str]] = None,
        forms: Optional[List[str]] = None,
        events: Optional[List[str]] = None,
        raw_or_label: Literal["raw", "label", "both"] = "raw",
        raw_or_label_headers: Literal["raw", "label"] = "raw",
        event_name: Literal["label", "unique"] = "label",
        record_type: Literal["flat", "eav"] = "flat",
        export_survey_fields: bool = False,
        export_data_access_groups: bool = False,
        export_checkbox_labels: bool = False,
        filter_logic: Optional[str] = None,
        date_begin: Optional[datetime] = None,
        date_end: Optional[datetime] = None,
        decimal_character: Optional[Literal[",", "."]] = None,
        export_blank_for_gray_form_status: Optional[bool] = None,
        df_kwargs: Optional[Dict[str, Any]] = None,
    ) -> str:
        ...

    @overload
    def export_records(
        self,
        format_type: Literal["df"],
        records: Optional[List[str]] = None,
        fields: Optional[List[str]] = None,
        forms: Optional[List[str]] = None,
        events: Optional[List[str]] = None,
        raw_or_label: Literal["raw", "label", "both"] = "raw",
        raw_or_label_headers: Literal["raw", "label"] = "raw",
        event_name: Literal["label", "unique"] = "label",
        record_type: Literal["flat", "eav"] = "flat",
        export_survey_fields: bool = False,
        export_data_access_groups: bool = False,
        export_checkbox_labels: bool = False,
        filter_logic: Optional[str] = None,
        date_begin: Optional[datetime] = None,
        date_end: Optional[datetime] = None,
        decimal_character: Optional[Literal[",", "."]] = None,
        export_blank_for_gray_form_status: Optional[bool] = None,
        df_kwargs: Optional[Dict[str, Any]] = None,
    ) -> "pd.DataFrame":
        ...

    def export_records(
        self,
        format_type: Literal["json", "csv", "xml", "df"] = "json",
        records: Optional[List[str]] = None,
        fields: Optional[List[str]] = None,
        forms: Optional[List[str]] = None,
        events: Optional[List[str]] = None,
        raw_or_label: Literal["raw", "label", "both"] = "raw",
        raw_or_label_headers: Literal["raw", "label"] = "raw",
        event_name: Literal["label", "unique"] = "label",
        record_type: Literal["flat", "eav"] = "flat",
        export_survey_fields: bool = False,
        export_data_access_groups: bool = False,
        export_checkbox_labels: bool = False,
        filter_logic: Optional[str] = None,
        date_begin: Optional[datetime] = None,
        date_end: Optional[datetime] = None,
        decimal_character: Optional[Literal[",", "."]] = None,
        export_blank_for_gray_form_status: Optional[bool] = None,
        df_kwargs: Optional[Dict[str, Any]] = None,
    ):
        # pylint: disable=line-too-long
        """
        Export data from the REDCap project.

        Args:
            format_type:
                Format of returned data. `'json'` returns json-decoded
                objects while `'csv'` and `'xml'` return other formats.
                `'df'` will attempt to return a `pandas.DataFrame`
            records:
                Array of record names specifying specific records to export.
                By default, all records are exported
            fields:
                Array of field names specifying specific fields to pull
                by default, all fields are exported
            forms:
                Array of form names to export. If in the web UI, the form
                name has a space in it, replace the space with an underscore
                By default, all forms are exported
            events:
                An array of unique event names from which to export records
                Note:
                    This only applies to longitudinal projects
            raw_or_label:
                Export the raw coded values or labels for the options of
                multiple choice fields, or both
            raw_or_label_headers:
                Export the column names of the instrument as their raw
                value or their labeled value
            event_name:
                Export the unique event name or the event label
            record_type:
                Database output structure type
            export_survey_fields:
                Specifies whether or not to export the survey identifier
                field (e.g., "redcap_survey_identifier") or survey timestamp
                fields (e.g., form_name+"_timestamp") when surveys are
                utilized in the project
            export_data_access_groups:
                Specifies whether or not to export the
                `"redcap_data_access_group"` field when data access groups
                are utilized in the project

                Note:
                    This flag is only viable if the user whose token is
                    being used to make the API request is *not* in a data
                    access group. If the user is in a group, then this flag
                    will revert to its default value.
            export_checkbox_labels:
                Specify whether to export checkbox values as their label on
                export.
            filter_logic:
                Filter which records are returned using REDCap conditional syntax
            date_begin:
                Filter on records created after a date
            date_end:
                Filter on records created before a date
            decimal_character:
                Force all numbers into same decimal format
            export_blank_for_gray_form_status:
                Whether or not to export blank values for instrument complete status fields
                that have a gray status icon
            df_kwargs:
                Passed to `pandas.read_csv` to control construction of
                returned DataFrame.
                By default, `{'index_col': self.def_field}`
        Returns:
            Union[List[Dict[str, Any]], str, pd.DataFrame]: Exported data

        Examples:
            >>> proj.export_records()
            [{'record_id': '1', 'redcap_event_name': 'event_1_arm_1', 'redcap_repeat_instrument': '',
            'redcap_repeat_instance': 1, 'field_1': '1',
            'checkbox_field___1': '0', 'checkbox_field___2': '1', 'upload_field': 'test_upload.txt',
            'form_1_complete': '2'},
            {'record_id': '2', 'redcap_event_name': 'event_1_arm_1', 'redcap_repeat_instrument': '',
            'redcap_repeat_instance': 1, 'field_1': '0',
            'checkbox_field___1': '0', 'checkbox_field___2': '0', 'upload_field': 'myupload.txt',
            'form_1_complete': '0'}]

            >>> proj.export_records(filter_logic="[field_1] = 1")
            [{'record_id': '1', 'redcap_event_name': 'event_1_arm_1', 'redcap_repeat_instrument': '',
            'redcap_repeat_instance': 1, 'field_1': '1',
            'checkbox_field___1': '0', 'checkbox_field___2': '1', 'upload_field': 'test_upload.txt',
            'form_1_complete': '2'}]

            >>> proj.export_records(
            ...     format_type="csv",
            ...     fields=["field_1", "checkbox_field"],
            ...     raw_or_label="label"
            ... )
            'field_1,checkbox_field___1,checkbox_field___2\\nYes,Unchecked,Checked\\nNo,Unchecked,Unchecked\\n'

{'fraction_non_alphanumeric': 0.10872707059477488, 'fraction_numerical': 0.004669260700389105, 'mean_word_length': 2.21957766642806, 'pattern_counts': {'":': 2, '<': 3, '<?xml version=': 0, '>': 27, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 6}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6057434', 'n_tokens_mistral': 5087, 'n_tokens_neox': 4924, 'n_words': 1417}