PyCap: Python interface to REDCap

PyCap provides abstractions for several REDCap API operations categorized into Export, Import, Delete, and Other.

Export capabilities include:

• Arms, Data Access Groups, Events, Field names, Instruments, Instrument-event mapping
• File, File Repository, Logging, Metadata, Project Info
• PDF of instruments, Records, Repeating instruments and events
• Report, Surveys, Users, User-DAG assignment, User Roles, User-Role assignment, Version

Import capabilities include:

• Arms, Data Access Groups, Events, File, File Repository, Instrument-event mapping, Metadata, Records, Repeating instruments and events, Users, User-DAG assignment, User Roles, User-Role assignment

Delete capabilities include:

• Arms, Data Access Groups, Events, File, File Repository, Records, Users, User Roles

Other capabilities include:

• Generate next record name
• Switch data access group

When integrating PyCap into an application or package, you can choose between the high-level Project class or more specialized subclasses depending on your scope:

• Use the Project class if you need a wide array of functionality (e.g., exporting records, managing surveys, or user management) or if you are writing a small, ad-hoc script.
• Use focused subclasses (like Records) if your application only interacts with a specific part of the REDCap API. This reduces complexity for the developer and minimizes dependencies for your application.

To connect to a REDCap project, first create a .env file (copy from .env.example) containing your REDCAP_API_URL and REDCAP_API_KEY. Use python-dotenv to load these credentials and instantiate a Project object from the redcap module.

from dotenv import load_dotenv
import os
from redcap import Project

load_dotenv()  # reads .env from the project root

api_url = os.environ["REDCAP_API_URL"]
api_key = os.environ["REDCAP_API_KEY"]
project = Project(api_url, api_key)

For secure credential management, it is recommended to use python-dotenv.

1. Install the package:

pip install python-dotenv

2. Create a .env file in your project root and add your REDCap credentials using the following keys:

REDCAP_API_URL=https://redcap.example.edu/api/
REDCAP_API_KEY=YourSuperSecretAPIKeyHere

If your application only needs to export or import data, use the Records class. It provides a focused interface for these tasks via the export_records and import_records methods.

Note that the Project class inherits these methods directly from the Records class, so the API usage is identical, but using Records directly allows for a lighter dependency footprint in your package.

To use PyCap securely, install python-dotenv and store your REDCap credentials in a .env file in your project root. This prevents hardcoding sensitive API keys in your source code.

1. Install the dependency: pip install python-dotenv or poetry add python-dotenv
2. Create a .env file with the following keys:
   • REDCAP_API_URL: The full URL to your REDCap API endpoint.
   • REDCAP_API_KEY: Your REDCap API token.
3. Use load_dotenv() to load these into your environment before initializing the Project object.

from dotenv import load_dotenv
import os
from redcap import Project

load_dotenv()  # Load variables from .env file

api_url = os.getenv('REDCAP_API_URL')
api_key = os.getenv('REDCAP_API_KEY')
project = Project(api_url, api_key)

Install the latest version of PyCap using pip. If you intend to load REDCap data into pandas dataframes, install the [all] extra to ensure pandas is included in your environment.

# Standard installation
$ pip install PyCap

# Installation with pandas support
$ pip install PyCap[all]

# Install bleeding edge version from GitHub
$ pip install -e git+https://github.com/redcap-tools/PyCap.git#egg=PyCap

You can install the latest version of PyCap using pip.

To install the base package:

pip install PyCap

To install PyCap with pandas support (useful for loading REDCap data directly into pandas DataFrames), use the [all] extra:

pip install PyCap[all]

To install the latest development version directly from the GitHub repository:

pip install -e git+https://github.com/redcap-tools/PyCap.git#egg=PyCap

$ pip install PyCap

Use import_file() to upload a file to a specific record and field.

Arguments:

• record_id: The ID of the record.
• field_name: The name of the file upload field.
• filename: The name to assign to the file.
• file_obj: A file-like object containing the data.

fname = 'something_to_upload.txt'
with open(fname, 'r') as fobj:
    project.import_file('1', 'file', fname, fobj)

Use import_records() to upload data. The input should be a list of dictionaries, where each dictionary represents a record. At minimum, each dictionary must include a 'record' key.

to_import = [{'record': 'foo', 'test_score': 'bar'}]
response = project.import_records(to_import)

Use export_file() to download a file from a specific record and field. It returns a tuple containing the file content (bytes) and a headers dictionary. You can use the 'name' key in the headers to determine the original filename.

content, headers = project.export_file('1', 'file')
with open(headers['name'], 'wb') as fobj:
    fobj.write(content)

Use the export_records() method on a Project instance to retrieve all data currently stored in the project.

data = project.export_records()