{"id":32401111,"url":"https://github.com/jubilee2/redcaplite","last_synced_at":"2026-01-20T17:31:18.559Z","repository":{"id":251426472,"uuid":"837285934","full_name":"jubilee2/RedcapLite","owner":"jubilee2","description":"A Lightweight Python Client for REDCap","archived":false,"fork":false,"pushed_at":"2025-10-01T22:07:07.000Z","size":170,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-01T22:13:02.258Z","etag":null,"topics":["python","redcap","redcap-api"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jubilee2.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2024-08-02T16:00:31.000Z","updated_at":"2025-10-01T22:07:09.000Z","dependencies_parsed_at":"2025-04-11T18:36:25.666Z","dependency_job_id":"ad19ca2f-dbda-403f-b4b6-d887448bbe07","html_url":"https://github.com/jubilee2/RedcapLite","commit_stats":null,"previous_names":["jubilee2/redcaplite"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/jubilee2/RedcapLite","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jubilee2%2FRedcapLite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jubilee2%2FRedcapLite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jubilee2%2FRedcapLite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jubilee2%2FRedcapLite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jubilee2","download_url":"https://codeload.github.com/jubilee2/RedcapLite/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jubilee2%2FRedcapLite/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280936381,"owners_count":26416543,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-25T02:00:06.499Z","response_time":81,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["python","redcap","redcap-api"],"created_at":"2025-10-25T09:50:12.519Z","updated_at":"2025-10-25T09:50:24.172Z","avatar_url":"https://github.com/jubilee2.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `redcaplite`\n\n![pytest](https://github.com/jubilee2/RedcapLite/actions/workflows/python-app.yml/badge.svg?branch=main)\n![PyPI - Version](https://img.shields.io/pypi/v/redcaplite)\n![PyPI - Downloads](https://img.shields.io/pypi/dm/redcaplite)\n[![PyPI Downloads](https://static.pepy.tech/badge/redcaplite/month)](https://pepy.tech/projects/redcaplite)\n[![PyPI Downloads](https://static.pepy.tech/badge/redcaplite)](https://pepy.tech/projects/redcaplite)\n\n**Lightweight, user-friendly Python client for the REDCap API.**\n\n`redcaplite` makes it easy to connect to your REDCap project and perform common operations with minimal code. Whether you're a researcher automating data pulls or a developer building integrations, `redcaplite` keeps things simple and efficient.\n\n## Key Features\n\n-   Intuitive interface for the most common REDCap API endpoints.\n-   Installable from PyPI and ready to use in seconds.\n-   Fully typed and tested for reliable data exchange.\n-   Minimal dependencies to keep your environment lean.\n\n## Prerequisites\nBefore using `redcaplite`, you need to obtain two key pieces of information from your REDCap project's API page:\n-   **API URL:** The web address (URL) for your REDCap API.\n-   **API Token:** Your unique access token for authenticating API requests to your REDCap project.\n\n## Installation\n\n### From PyPI (Recommended)\nTo install `redcaplite` from the Python Package Index (PyPI), run the following command in your terminal:\n```sh\npip install redcaplite\n```\nThis is the recommended installation method for most users.\n\n### From Source (for Development)\nIf you plan to contribute to `redcaplite` or require the latest development version, you can install it directly from the source code:\n1.  Clone the repository:\n    ```sh\n    git clone https://github.com/jubilee2/RedcapLite.git\n    ```\n2.  Navigate to the cloned directory:\n    ```sh\n    cd RedcapLite\n    ```\n3.  Install the package in editable mode (this allows your changes to be immediately reflected):\n    ```sh\n    pip install -e .\n    ```\nThis setup installs the package locally, making any modifications to the source code instantly available in your environment.\n\n## Quick Start\nHere's a quick example to get you started with `redcaplite`. This snippet demonstrates how to initialize the client and fetch basic project information.\n\n```python\nfrom redcaplite import RedcapClient\n\n# Replace 'YOUR_REDCAP_API_URL' and 'YOUR_REDCAP_API_TOKEN' with your actual API URL and token.\nAPI_URL = 'YOUR_REDCAP_API_URL'\nAPI_TOKEN = 'YOUR_REDCAP_API_TOKEN'\n\n# Create a RedcapClient instance\ntry:\n    client = RedcapClient(API_URL, API_TOKEN)\n\n    # Get basic project information\n    project_info = client.get_project()\n    print(\"Project Information:\")\n    if project_info: # project_info will be a dictionary on success\n        print(f\"  Project ID: {project_info.get('project_id')}\")\n        print(f\"  Project Title: {project_info.get('project_title')}\")\n        print(f\"  REDCap Version: {project_info.get('redcap_version')}\")\n    else:\n        # This else block might be reached if the API returns an unexpected empty response\n        # or if client.get_project() itself returns None on certain errors (check its implementation).\n        print(\"Could not retrieve project information. The response was empty or unexpected.\")\n        print(\"Please verify your API URL, token, and project permissions.\")\n\nexcept Exception as e:\n    print(f\"An error occurred during API interaction: {e}\")\n    print(\"Please ensure your API URL and token are correct, the REDCap API is accessible, and your project has API permissions enabled.\")\n\n```\n\n## Detailed Usage\n\n### Importing the Package\n\nTo use `redcaplite` in your Python script, import the necessary components:\n\n```python\nimport redcaplite # Or, more commonly:\n# from redcaplite import RedcapClient\n```\n\n### Creating an Instance\n\nInstantiate the `RedcapClient` class by providing your REDCap API URL and token:\n\n```python\nfrom redcaplite import RedcapClient\n\n# Replace with your actual API URL and token\nAPI_URL = 'YOUR_REDCAP_API_URL' # e.g., 'https://redcap.yourinstitution.org/api/'\nAPI_TOKEN = 'YOUR_REDCAP_API_TOKEN' # e.g., 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'\n\nclient = RedcapClient(API_URL, API_TOKEN)\n# Now 'client' can be used to call various API methods.\n# For example: project_details = client.get_project()\n# It's good practice to wrap API calls in try-except blocks, as shown in the Quick Start section.\n```\n\n### Methods\n\nThe `RedcapClient` provides a wide range of methods to interact with the REDCap API. Here is a comprehensive list, categorized by typical REDCap actions (Export, Import, Delete). Not all actions are available for every API endpoint.\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to expand/collapse the full list of API methods\u003c/summary\u003e\n\n| API Name | Export | Import | Delete |\n|---|---|---|---|\n| Arms | `get_arms()` | `import_arms()` | `delete_arms()` |\n| DAGs | `get_dags()` | `import_dags()` | `delete_dags()` |\n| User DAG Mapping | `get_user_dag_mappings()` | `import_user_dag_mappings()` |  |\n| Events | `get_events()` | `import_events()` | `delete_events()` |\n| Field Names | `get_field_names()` |  |  |\n| File | `get_file()` | `import_file()` | `delete_file()` | \n| File Repository (File) | `export_file_repository()` | `import_file_repository()` | `delete_file_repository()` |\n| File Repository (Folder)| `list_file_repository()` | `create_folder_file_repository()` |  | \n| Instrument | `get_instruments()` |  |  |\n| Instrument (PDF)| `export_pdf()` |  |  |\n| Form Event Mapping | `get_form_event_mappings()` | `import_form_event_mappings()` |  |\n| Log | `get_logs()` |  |  |\n| Metadata | `get_metadata()` | `import_metadata()` |  |\n| Project | `get_project()`\u003cbr\u003e`get_project_xml()` | `import_project_settings()` |  |\n| Project (super user) |  | `create_project()` |  |\n| Record | `export_records()`\u003cbr\u003e`generate_next_record_name()` | `import_records()`\u003cbr\u003e`rename_record()` | `delete_records()` |\n| Repeating Forms Events | `get_repeating_forms_events()` | `import_repeating_forms_events()` |  |\n| Report | `get_report()` |  |  |\n| Version | `get_version()` |  |  |\n| Survey | `get_survey_link()`\u003cbr\u003e`get_survey_queue_link()`\u003cbr\u003e`get_survey_return_code()`\u003cbr\u003e`get_participant_list()` |  |  |\n| Users | `get_users()` | `import_users()` | `delete_users()` |\n| User Role | `get_user_roles()` | `import_user_roles()` | `delete_user_roles()` |\n| User Role Mapping | `get_user_role_mappings()` | `import_user_role_mappings()` |  |\n\n\u003c/details\u003e\n\n### Example\n\nHere’s a complete example of how to use the `redcaplite` package:\n\n```python\nimport redcaplite\n\n# Create an instance of RedcapClient\nr = redcaplite.RedcapClient('https://redcap.vumc.org/api/', 'your_token')\n\n# Get arms\narms = r.get_arms()\nprint(\"Arms:\", arms)\n\n# Delete specific arms\nr.delete_arms(arms=[3])\nprint(\"Arm 3 deleted successfully.\")\n```\n\n### Advanced: Customizing CSV Exports with `pd_read_csv_kwargs`\n\nWhen exporting data in CSV format using methods like `export_records()` or `get_report()`, `redcaplite` internally uses `pandas.read_csv()` to parse the initial response from REDCap. The `pd_read_csv_kwargs` parameter allows you to pass additional keyword arguments directly to `pandas.read_csv()`, giving you finer control over data type conversion and other parsing aspects.\n\n#### Handling Data Types with `dtype`\n\nA common use case for `pd_read_csv_kwargs` is to specify the data type of specific columns. For instance, to ensure a column like `participant_study_id` is treated as a string (preventing automatic conversion to a numeric type if it contains only digits), you can do the following:\n\n```python\n# When calling export_records or get_report\nresponse = client.export_records(\n    format='csv', \n    # ... other parameters ...\n    pd_read_csv_kwargs={'dtype': {'participant_study_id': str}}\n)\n# Or for a specific report:\n# report_data = client.get_report(\n#     report_id='YOUR_REPORT_ID',\n#     format='csv',\n#     pd_read_csv_kwargs={'dtype': {'participant_study_id': str, 'another_id_field': str}}\n# )\n\n```\n\nIn this example, the `dtype` dictionary passed within `pd_read_csv_kwargs` instructs pandas to treat the `participant_study_id` column as `str` (string).\n\n#### Benefits of using `pd_read_csv_kwargs`\n\n-   **Preserve Data Integrity:** Ensure that sensitive data, like participant IDs, are maintained in their original string format, preventing unintended numeric conversions.\n-   **Avoid Downstream Errors:** Prevent issues related to automatic data type conversions that might cause errors or unexpected behavior in subsequent data processing steps.\n-   **Leverage Pandas Power:** Utilize pandas' robust data type handling capabilities to fine-tune your data parsing directly at the point of API interaction.\n\nThis feature is particularly useful for maintaining data consistency, especially for columns that might contain leading zeros or mixed alphanumeric characters but could be misinterpreted as numeric.\n\nWe hope this new feature helps you to work more efficiently and effectively with your REDCap data!\n\n## Contributing\n\nContributions to `redcaplite` are welcome! If you would like to contribute, please fork the repository, make your changes, and submit a pull request.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjubilee2%2Fredcaplite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjubilee2%2Fredcaplite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjubilee2%2Fredcaplite/lists"}