Add parents/ancestry methods

[jm-rivera]

This PR is part of a group of PRs which will bring some key features from the Data Commons website API to the client library (e.g #229, #230)

TL;DR
Fetch entity parents: A new Node method (fetch_entity_parents) which uses containedInPlace to get the immediate parents for a given entity or list of entities.
Fetch entity ancestry: A new Node method fetch_entity_ancestry performs a parallel breadth-first traversal to construct the full ancestry chain for an entity — all the way up to Earth — and returns it in either flat or nested form.

---

With this PR, I aimed to replicate the /api/place/parent of the website API. Under the hood, this endpoint relies on legacy calls to the REST V1 bulk info endpoint.

Being able to get the full ancestry for an entity (or list of entities) is a very helpful feature. However, doing this through the Node endpoint requires recursively resolving each parent until you reach the root of the place graph (in this case always "Earth"). This PR introduces logic to make that process as efficient and easy to use as possible for users (and being careful not to make any repeated or unnecessary calls to the API).

• Breadth-first traversal: I used a breadth-first approach (build_ancestry_map) to ensure we resolve ancestry level by level, starting from the root entity. This avoids recursion and makes parallel execution easier to manage and reason about.
• Parallel fetching with threads: Since every level of the graph may require one or more network calls to resolve containedInPlace, I used ThreadPoolExecutor to fetch parent nodes in parallel. This drastically reduces total resolution time for large (e.g many entities) or deep ancestry chains (e.g. "Kampala" -> "Uganda" -> "Africa" -> "Earth").
• Memoization with LRU cache: To avoid repeated API calls for shared parents (e.g. if two cities belong to the same country, two countries to the same region, etc.), I used an @lru_cache wrapper on the fetcher. This ensures we only fetch a node’s parents once per ancestry resolution session.

The data can be returned as two different types:

• A flat list of parent dicts (as_tree=False) mirrors the structure returned by the website’s /api/place/parent — for parity with the website version or cases when only the list of upstream places is needed.
• A nested ancestry tree (as_tree=True) returns a full parent-child hierarchy rooted at the input entity. Note that not all nodes in the place graph appear to be fully connected — this method doesn’t attempt to infer or resolve missing links in the hierarchy.

---

Example usage:

For entity parents

from datacommons_client import DataCommonsClient

dc = DataCommonsClient(dc_instance="datacommons.one.org")

parents = dc.node.fetch_entity_parents(entity_dcids=[
    "africa",
    "wikidataId/Q2608785",
])

{'africa': [{'dcid': 'Earth', 'name': 'World', 'type': 'Place'}],
 'wikidataId/Q2608785': [{'dcid': 'country/GTM',
                          'name': 'Guatemala',
                          'type': 'Country'}]}

By itself, the above doesn't match the website endpoint, or provide a complete ancestry.

Full ancestry

from datacommons_client import DataCommonsClient

dc = DataCommonsClient(dc_instance="datacommons.one.org")

parents = dc.node.fetch_entity_ancestry(
    entity_dcids=[
        "africa",
        "wikidataId/Q2608785",
    ],
    as_tree=False,
)


{'africa': [{'dcid': 'Earth', 'name': 'World', 'type': 'Place'}],
 'wikidataId/Q2608785': [{'dcid': 'country/GTM',
                          'name': 'Guatemala',
                          'type': 'Country'},
                         {'dcid': 'CentralAmerica',
                          'name': 'Central America (including Mexico)',
                          'type': 'UNGeoRegion'},
                         {'dcid': 'LatinAmericaAndCaribbean',
                          'name': 'Latin America and the Caribbean',
                          'type': 'UNGeoRegion'},
                         {'dcid': 'northamerica',
                          'name': 'North America',
                          'type': 'Continent'},
                         {'dcid': 'undata-geo/G00134000',
                          'name': 'Americas',
                          'type': 'GeoRegion'},
                         {'dcid': 'Earth', 'name': 'World', 'type': 'Place'}]}

Which can also be returned as a nested structure:

parents = dc.node.fetch_entity_ancestry(
    entity_dcids=[
        "africa",
        "wikidataId/Q2608785",
    ],
    as_tree=True,
)

{'africa': {'dcid': 'africa',
            'name': None,
            'parents': [{'dcid': 'Earth',
                         'name': 'World',
                         'parents': [],
                         'type': 'Place'}],
            'type': None},
 'wikidataId/Q2608785': {'dcid': 'wikidataId/Q2608785',
                         'name': None,
                         'parents': [{'dcid': 'country/GTM',
                                      'name': 'Guatemala',
                                      'parents': [{'dcid': 'CentralAmerica',
                                                   'name': 'Central America '
                                                           '(including Mexico)',
                                                   'parents': [{'dcid': 'Earth',
                                                                'name': 'World',
                                                                'parents': [],
                                                                'type': 'Place'},
                                                               {'dcid': 'LatinAmericaAndCaribbean',
                                                                'name': 'Latin '
                                                                        'America '
                                                                        'and '
                                                                        'the '
                                                                        'Caribbean',
                                                                'parents': [],
                                                                'type': 'UNGeoRegion'},
                                                               {'dcid': 'undata-geo/G00134000',
                                                                'name': 'Americas',
                                                                'parents': [],
                                                                'type': 'GeoRegion'}],
                                                   'type': 'UNGeoRegion'},
                                                  {'dcid': 'LatinAmericaAndCaribbean',
                                                   'name': 'Latin America and the Caribbean',
                                                   'parents': [{'dcid': 'Earth',
                                                                'name': 'World',
                                                                'parents': [],
                                                                'type': 'Place'},
                                                               {'dcid': 'undata-geo/G00134000',
                                                                'name': 'Americas',
                                                                'parents': [],
                                                                'type': 'GeoRegion'}],
                                                   'type': 'UNGeoRegion'},
                                                  {'dcid': 'northamerica',
                                                   'name': 'North America',
                                                   'parents': [{'dcid': 'Earth',
                                                                'name': 'World',
                                                                'parents': [],
                                                                'type': 'Place'}],
                                                   'type': 'Continent'},
                                                  {'dcid': 'undata-geo/G00134000',
                                                   'name': 'Americas',
                                                   'parents': [{'dcid': 'Earth',
                                                                'name': 'World',
                                                                'parents': [],
                                                                'type': 'Place'}],
                                                   'type': 'GeoRegion'}],
                                      'type': 'Country'}],
                         'type': None}}

[dwnoble]

Could you add the number of works as an optional argument to the fetch_entity_ancestry function?

[jm-rivera]

Done as max_concurrent_requests for a more user-friendly name. It defaults to ANCESTRY_MAX_WORKERS

[dwnoble]

What do you think making the name Parent more general. Maybe Entity or Node?

[jm-rivera]

Thanks @dwnoble!

Node already exists. It's indeed more general.

The only reason why I created Parent was to match the website API return format.

[
  {
    "dcid": "undata-geo/G00134000",
    "name": "Americas",
    "type": "GeoRegion"
  },
  {
    "dcid": "northamerica",
    "name": "North America",
    "type": "Continent"
  },
  {
    "dcid": "LatinAmericaAndCaribbean",
    "name": "Latin America and the Caribbean",
    "type": "UNGeoRegion"
  },
  {
    "dcid": "CentralAmerica",
    "name": "Central America (including Mexico)",
    "type": "UNGeoRegion"
  },
  {
    "dcid": "Earth",
    "name": "World",
    "type": "Place"
  }
]

If you prefer, we could get rid of this Parent class and just use Node. The only downside is that divergence, but maybe that's ok. Let me know!

[dwnoble]

I'm fine re-using node, and eventually updating the website API response to use the node response as well

[dwnoble]

Same here- can this be an optional param for the user-facing function?

[jm-rivera]

This is already the case. Here's the function signature:

def build_ancestry_map(
    root: str,
    fetch_fn: Callable[[str], tuple[Parent, ...]],
    max_workers: Optional[int] = PARENTS_MAX_WORKERS,
) -> tuple[str, AncestryMap]

Or did you mean something different?

[dwnoble]

I was thinking about adding it as a parameter to fetch_entity_ancestry. Though that could get a little confusing having two concurrency params