somacore

library2.0.0pypypi✓ verified 90d ago

somacore provides the Python-language API specification and base utilities for the SOMA (Scalable Open Multi-omics Array) system. It defines abstract base classes and protocols for core SOMA objects like Experiment, Measurement, DataFrame, and Arrays. As of version 1.0.29, it focuses on defining the SOMA data model for interoperability. The library is actively maintained with frequent updates, often aligning with updates to the broader SOMA specification.

data database

pip install somacore

github ↗package ↗

INSTALL

IMPORT

SIG · SOMACORE

somacore

datapythonv2.0.0

Install

15.2s avg

Import

2753ms

Disk

512MB

Pass rate

6/ 10

Env Coverage6 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.0.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✓ —

✓ 14.2s

py 3.11

✕ build_error

✓ 15.35s

py 3.12

✕ build_error

✓ 15.15s

py 3.13

✕ build_error

✓ 15.1s

py 3.9

✕ build_error

✓ 16s

512MB installed

● package 512MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SOMAObject

✓ from somacore import SOMAObject

DataFrame

✓ from somacore import DataFrame

✗ from somacore.base import DataFrame

Core SOMA types are typically imported directly from the top-level `somacore` package.

Axis

✓ from somacore import Axis

OpenMode

✓ from somacore import OpenMode

query

✓ from somacore.query import query

This quickstart demonstrates importing core `somacore` types and enumerations. It highlights that `somacore` provides abstract definitions and protocols for the SOMA data model, which are not directly instantiable. Instead, concrete implementations (like `tiledbsoma`) are required to create and manipulate SOMA objects. The example shows how to access the library version and inspect available enumeration values.

import somacore from somacore import AxisType, OpenMode, SOMAObject # somacore provides abstract base classes (Protocols) # for SOMA objects and related concepts. print(f"somacore version: {somacore.__version__}") # You can import and inspect enumeration types print(f"Available Axis Types: {list(AxisType)}") print(f"Read mode for opening objects: {OpenMode.READ}") # SOMAObject is a core Protocol (an Abstract Base Class for type hinting) print(f"SOMAObject is a {type(SOMAObject).__name__}") # You cannot instantiate these protocols directly; # they are meant for type checking and as interfaces for implementations. # For example, this would raise a TypeError: # try: # obj = SOMAObject("some_uri") # except TypeError as e: # print(f"\nCannot instantiate SOMAObject directly: {e}") print("\nsomacore defines the SOMA API. For concrete implementations,") print("refer to libraries like `tiledbsoma` which implement these protocols.")

Debug

Known issues

breakingThe SOMA API specification underwent significant changes with the 1.0.0 release. Code written for `somacore` 0.x (and earlier versions of SOMA implementations) is generally incompatible with `somacore` 1.x.

fix

Update your code to conform to the SOMA API v1.0 specification. Consult `somacore` 1.x documentation and migration guides for your chosen SOMA implementation (e.g., `tiledbsoma`) to adapt to the new API.

affects: 0.x

gotcha`somacore` solely defines the SOMA API specification and provides abstract types (Protocols/ABCs). It does not provide concrete, instantiable SOMA objects, data storage mechanisms, or I/O operations itself.

fix

To work with actual SOMA objects and data, you must install and use a specific SOMA implementation library (e.g., `tiledbsoma`), which provides concrete classes that adhere to the `somacore` protocols and handles data persistence.

affects: All versions

gotchaSOMA objects (e.g., `Experiment`, `DataFrame`) are represented as Python `Protocol`s in `somacore`. While they define interfaces for type checking, they are not intended for direct instantiation or subclassing by users without a concrete implementation.

fix

Use concrete SOMA object classes provided by an implementation library (e.g., `tiledbsoma.SOMACollection`) when creating or interacting with SOMA data structures. `somacore` types should primarily be used for type hinting.

affects: All versions

Errors

Common errors & fixes

TypeError: SOMAObject cannot be instantiated directly

Attempting to create an instance of an abstract SOMA type (protocol) directly from `somacore`.

fix

Import and use concrete SOMA object classes provided by an implementation library, such as `tiledbsoma.SOMACollection` or `tiledbsoma.SOMADataFrame`, which adhere to the `somacore` protocols.

AttributeError: module 'somacore' has no attribute 'Experiment' (or similar for other concrete classes like 'DataFrame')

Expecting `somacore` to expose concrete SOMA implementation classes directly, rather than abstract definitions.

fix

`somacore` provides abstract definitions. For concrete SOMA objects like `Experiment` or `DataFrame` that you can instantiate and populate, you need to import them from a specific SOMA implementation library (e.g., `from tiledbsoma import Experiment`).

ModuleNotFoundError: No module named 'somacore.experiment'

Trying to import a specific, concrete SOMA object like `Experiment` from a sub-module of `somacore` based on an incorrect assumption about its structure.

fix

Concrete SOMA objects like `Experiment` are typically provided by SOMA implementation libraries (e.g., `tiledbsoma`) and imported from their top-level package, not from `somacore` or its submodules. Check the documentation of your chosen SOMA implementation.

Upgrade

Version history

2.0.0latest on PyPI · released Apr 17, 2026

Audit

Dependencies

packagingrequiredUsed for version parsing and compatibility checks.

typing_extensionsrequiredProvides backports for newer typing features, especially Protocols, for wider Python version compatibility.

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/single-cell-data/SOMA.git ↗

packagehttps://pypi.org/project/somacore/ ↗