irw 0.1.3__tar.gz

irw-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hansol Lee, Ben Domingue
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

irw-0.1.3/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: irw
+Version: 0.1.3
+Summary: A Python package for the Item Response Warehouse (IRW)
+Author-email: Hansol Lee <hansol@stanford.edu>, Ben Domingue <bdomingu@stanford.edu>
+License-Expression: MIT
+Project-URL: Homepage, https://itemresponsewarehouse.org/
+Project-URL: Repository, https://github.com/itemresponsewarehouse/Python-pkg
+Project-URL: Issues, https://github.com/itemresponsewarehouse/Python-pkg/issues
+Project-URL: Changelog, https://github.com/itemresponsewarehouse/Python-pkg/releases
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: redivis>=0.20.14
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: numpy>=1.20.0
+Dynamic: license-file
+
+# `irw`: A Python Package for the Item Response Warehouse
+
+This repository hosts the Python package `irw`, which provides programmatic access to the [Item Response Warehouse (IRW)](https://itemresponsewarehouse.org/), an open repository of harmonized item response data hosted on Redivis.
+
+Project map: [`ARCHITECTURE.md`](https://github.com/ben-domingue/irw/blob/main/ARCHITECTURE.md) in `ben-domingue/irw` — which repo owns
+what, where the data lives, and which document is authoritative when two disagree.
+
+## Installation
+
+**Recommended: Use a virtual environment** (prevents conflicts with other packages):
+
+```bash
+# Create and activate a virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install the package
+python -m pip install --upgrade pip
+python -m pip install "git+https://github.com/itemresponsewarehouse/Python-pkg.git"
+```
+
+### Requirements
+
+- Python 3.9 or higher
+- pip 
+
+If you encounter any installation issues, please [open an issue](https://github.com/itemresponsewarehouse/Python-pkg/issues).
+
+## IMPORTANT: Redivis Authentication
+
+The IRW tables are hosted on [Redivis](https://redivis.com), a data management platform. To access these datasets, you'll need to:
+
+1. Have a Redivis account (create one at <https://redivis.com/?createAccount> if you don't have one).
+
+2. Authenticate using the Redivis Python Client:
+   1. When you first use a function in `irw` that connects to Redivis (e.g. `list_tables()`), a browser window will open, prompting you to sign in to your Redivis account.
+   2. After signing in, click **Allow** to grant access for the Redivis Python Client.
+   3. Once authentication is successful, close the browser window. You will see the message "Authentication was successful" in console.
+
+**Note:** You only need to authenticate once per session. For detailed instructions, refer to the [Redivis Python Client documentation](https://apidocs.redivis.com/client-libraries/redivis-python).
+
+## Usage Examples
+
+See the `examples/` directory:
+- `example.py` - Complete workflow example
+- `available_methods.md` - Reference guide for all available methods
+
+Example workflow:
+```python
+import irw
+
+# Get database information
+irw.info()
+
+# View available tables
+tables = irw.list_tables()
+tables_with_metadata = irw.list_tables(include_metadata=True)
+
+# Get table info
+irw.info("agn_kay_2025")  # Table metadata
+
+# Fetch a table
+df = irw.fetch("agn_kay_2025")
+# Convert to response matrix
+resp_matrix = irw.long2resp(df)
+
+# Explore available filters
+filters = irw.get_filters()  # Returns list of filter names
+irw.describe_filter('construct_type')  # Get values for a specific filter
+
+# Filter and fetch tables
+filtered = irw.filter(n_responses=[1000, None], construct_type="Affective/mental health")
+dfs = irw.fetch(filtered)
+
+# Get BibTeX citation
+irw.save_bibtex("agn_kay_2025")  # Returns BibTeX entry
+# Download table
+irw.download("agn_kay_2025", path="data.csv")
+
+# Browse collections: labelled groupings of tables
+irw.collections()                     # all collections, with coverage and table counts
+tabs = irw.collection("depression")   # the table names in one collection
+irw.collection_members(tables="frac20")  # which collections is this table in?
+
+# Which version of IRW is this? (cite this number)
+irw.version()                         # newest IRW version and its dataset pins
+irw.version("2026-08-01")             # what was live on that date
+```
+
+## Development
+
+### Setting up Development Environment
+
+1. **Clone the repository**:
+   ```bash
+   git clone https://github.com/itemresponsewarehouse/Python-pkg.git
+   cd Python-pkg
+   ```
+
+2. **Create a virtual environment**:
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+
+3. **Install development dependencies**:
+   ```bash
+   pip install -e .
+   ```
+
+## Feedback and Contributions
+
+If you encounter issues or have suggestions for improving `irw`, please submit them on the [GitHub Issues page](https://github.com/itemresponsewarehouse/Python-pkg/issues). Contributions are welcome!

irw-0.1.3/README.md

@@ -0,0 +1,113 @@
+# `irw`: A Python Package for the Item Response Warehouse
+
+This repository hosts the Python package `irw`, which provides programmatic access to the [Item Response Warehouse (IRW)](https://itemresponsewarehouse.org/), an open repository of harmonized item response data hosted on Redivis.
+
+Project map: [`ARCHITECTURE.md`](https://github.com/ben-domingue/irw/blob/main/ARCHITECTURE.md) in `ben-domingue/irw` — which repo owns
+what, where the data lives, and which document is authoritative when two disagree.
+
+## Installation
+
+**Recommended: Use a virtual environment** (prevents conflicts with other packages):
+
+```bash
+# Create and activate a virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install the package
+python -m pip install --upgrade pip
+python -m pip install "git+https://github.com/itemresponsewarehouse/Python-pkg.git"
+```
+
+### Requirements
+
+- Python 3.9 or higher
+- pip 
+
+If you encounter any installation issues, please [open an issue](https://github.com/itemresponsewarehouse/Python-pkg/issues).
+
+## IMPORTANT: Redivis Authentication
+
+The IRW tables are hosted on [Redivis](https://redivis.com), a data management platform. To access these datasets, you'll need to:
+
+1. Have a Redivis account (create one at <https://redivis.com/?createAccount> if you don't have one).
+
+2. Authenticate using the Redivis Python Client:
+   1. When you first use a function in `irw` that connects to Redivis (e.g. `list_tables()`), a browser window will open, prompting you to sign in to your Redivis account.
+   2. After signing in, click **Allow** to grant access for the Redivis Python Client.
+   3. Once authentication is successful, close the browser window. You will see the message "Authentication was successful" in console.
+
+**Note:** You only need to authenticate once per session. For detailed instructions, refer to the [Redivis Python Client documentation](https://apidocs.redivis.com/client-libraries/redivis-python).
+
+## Usage Examples
+
+See the `examples/` directory:
+- `example.py` - Complete workflow example
+- `available_methods.md` - Reference guide for all available methods
+
+Example workflow:
+```python
+import irw
+
+# Get database information
+irw.info()
+
+# View available tables
+tables = irw.list_tables()
+tables_with_metadata = irw.list_tables(include_metadata=True)
+
+# Get table info
+irw.info("agn_kay_2025")  # Table metadata
+
+# Fetch a table
+df = irw.fetch("agn_kay_2025")
+# Convert to response matrix
+resp_matrix = irw.long2resp(df)
+
+# Explore available filters
+filters = irw.get_filters()  # Returns list of filter names
+irw.describe_filter('construct_type')  # Get values for a specific filter
+
+# Filter and fetch tables
+filtered = irw.filter(n_responses=[1000, None], construct_type="Affective/mental health")
+dfs = irw.fetch(filtered)
+
+# Get BibTeX citation
+irw.save_bibtex("agn_kay_2025")  # Returns BibTeX entry
+# Download table
+irw.download("agn_kay_2025", path="data.csv")
+
+# Browse collections: labelled groupings of tables
+irw.collections()                     # all collections, with coverage and table counts
+tabs = irw.collection("depression")   # the table names in one collection
+irw.collection_members(tables="frac20")  # which collections is this table in?
+
+# Which version of IRW is this? (cite this number)
+irw.version()                         # newest IRW version and its dataset pins
+irw.version("2026-08-01")             # what was live on that date
+```
+
+## Development
+
+### Setting up Development Environment
+
+1. **Clone the repository**:
+   ```bash
+   git clone https://github.com/itemresponsewarehouse/Python-pkg.git
+   cd Python-pkg
+   ```
+
+2. **Create a virtual environment**:
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+
+3. **Install development dependencies**:
+   ```bash
+   pip install -e .
+   ```
+
+## Feedback and Contributions
+
+If you encounter issues or have suggestions for improving `irw`, please submit them on the [GitHub Issues page](https://github.com/itemresponsewarehouse/Python-pkg/issues). Contributions are welcome!

irw-0.1.3/pyproject.toml

@@ -0,0 +1,83 @@
+[build-system]
+# setuptools>=77 is a floor, not a preference. The `license = "MIT"` /
+# `license-files` pair below is PEP 639, which setuptools only understands from
+# 77.0.0. An isolated build (`python -m build`) resolves the newest setuptools
+# and is fine either way, but a NON-isolated build on an older one does not
+# error -- it silently emits `Name: UNKNOWN, Version: 0.0.0`, which is what the
+# stale UNKNOWN.egg-info/ in some working trees came from. That is the one
+# failure mode that could put an artifact on PyPI under the wrong name.
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "irw"
+version = "0.1.3"
+authors = [
+  { name="Hansol Lee", email="hansol@stanford.edu" },
+  { name="Ben Domingue", email="bdomingu@stanford.edu" }
+]
+description = "A Python package for the Item Response Warehouse (IRW)"
+readme = "README.md"
+requires-python = ">=3.9"
+# redivis>=0.20.14 is a floor, not a preference. Every client before it fails
+# with a pyarrow OSError ("Expected to be able to read N bytes for message
+# body") on any Redivis table over roughly a thousand rows, which takes out
+# every IRW metadata fetch and with it filter(), info() and
+# list_tables(include_metadata=True). Fixed upstream in 0.20.14. See issue #5.
+dependencies = [
+    "redivis>=0.20.14",
+    "pandas>=1.3.0",
+    "numpy>=1.20.0",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+]
+
+
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.urls]
+Homepage = "https://itemresponsewarehouse.org/"
+Repository = "https://github.com/itemresponsewarehouse/Python-pkg"
+Issues = "https://github.com/itemresponsewarehouse/Python-pkg/issues"
+Changelog = "https://github.com/itemresponsewarehouse/Python-pkg/releases"
+
+# Lint only -- there is deliberately no formatter here. A formatter reflows
+# every file at once, which makes `git blame` less useful across the whole
+# package and turns any in-flight branch into a conflict; the value was not
+# judged worth that. See issue #33.
+#
+# The rule set is ruff's non-formatting default (E4/E7/E9 + F): real problems
+# such as undefined names and dead imports. Style rules that would churn the
+# tree are deliberately out -- E501 (line-too-long) alone flagged 126 lines
+# and I001 (import sorting) 23 files. Add a rule only with the churn it costs
+# in view.
+[tool.ruff]
+target-version = "py39"
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F"]
+
+[tool.ruff.lint.per-file-ignores]
+# Both files import after top-level statements on purpose: __init__.py installs
+# warning filters that must be in place before the Redivis client is imported,
+# and the integration tests set a module-level skipif before importing irw.
+"src/irw/__init__.py" = ["E402"]
+"tests/test_redivis_integration.py" = ["E402"]

irw-0.1.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

irw-0.1.3/src/irw/__init__.py

@@ -0,0 +1,83 @@
+"""
+irw: A Python package for the Item Response Warehouse
+
+This package provides programmatic access to the Item Response Warehouse (IRW),
+an open repository of harmonized item response data.
+
+Usage:
+    import irw
+    
+    # Database operations
+    irw.list_tables()
+    irw.filter(construct_type="Affective/mental health")
+    irw.info()  # Database info
+    irw.info("agn_kay_2025")  # Table info
+    
+    # Table operations
+    df = irw.fetch("agn_kay_2025")
+    irw.itemtext("agn_kay_2025")
+    irw.save_bibtex("agn_kay_2025")
+    irw.download("agn_kay_2025")
+    resp_matrix = irw.long2resp(df)
+"""
+
+# Suppress known warnings
+import warnings
+# Redivis suggests qualifying every table as `name:refid`. We deliberately do
+# not for the IRW metadata tables: reference ids are reminted on every release,
+# so a pinned id stops resolving in the next version. See config.META_TABLES.
+warnings.filterwarnings(
+    "ignore",
+    message=".*No reference id was provided for the table.*",
+    category=UserWarning,
+)
+warnings.filterwarnings(
+    "ignore",
+    message=".*pkg_resources is deprecated.*",
+    category=UserWarning,
+)
+
+# Export all API functions
+from .api import (
+    list_tables,
+    filter,
+    info,
+    fetch,
+    itemtext,
+    save_bibtex,
+    download,
+    long2resp,
+    get_filters,
+    describe_filter,
+    list_tables_with_itemtext,
+    collections,
+    collection,
+    collection_members,
+    version,
+)
+from .operations.list_tables import IRWMetadataUnavailable
+
+__all__ = [
+    "IRWMetadataUnavailable",
+    "list_tables",
+    "filter",
+    "info",
+    "fetch",
+    "itemtext",
+    "save_bibtex",
+    "download",
+    "long2resp",
+    "get_filters",
+    "describe_filter",
+    "list_tables_with_itemtext",
+    "collections",
+    "collection",
+    "collection_members",
+    "version",
+]
+
+# Single source of truth is config.VERSION -- these two literals had drifted
+# apart (0.0.1 here, 0.0.2 there), so a user could not tell what they had.
+from .config import VERSION as VERSION
+
+__version__ = VERSION