langchain-xdataapi 0.1.0__tar.gz → 0.1.1__tar.gz

{langchain_xdataapi-0.1.0 → langchain_xdataapi-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: langchain-xdataapi
-Version: 0.1.0
+Version: 0.1.1
 Summary: LangChain tools for xdataapi.io: read-only public X (Twitter) profiles, tweets, threads, followers and search.
 Project-URL: Homepage, https://xdataapi.io
 Project-URL: Documentation, https://xdataapi.io/docs
@@ -68,8 +68,8 @@ print(search.invoke({"q": "from:vercel since:2026-09-01", "count": 10}))
 | Tool | Reads | Credits |
 |---|---|---|
 | `x_search_tweets` | Search with the x.com operators | 1 per result |
-| `x_get_user` | One profile | 1 |
-| `x_get_users` | Up to 100 profiles in one call | 1 per profile |
+| `x_get_user` | One profile, by `handle` or by numeric user `id` | 1 |
+| `x_get_users` | Up to 100 profiles in one call, by `handles` or by `ids` | 1 per profile |
 | `x_get_user_tweets` | Latest posts of a user | 1 per post |
 | `x_get_tweet` | One post | 1 |
 | `x_get_tweets` | Up to 100 posts in one call | 1 per post |

{langchain_xdataapi-0.1.0 → langchain_xdataapi-0.1.1}/README.md

@@ -46,8 +46,8 @@ print(search.invoke({"q": "from:vercel since:2026-09-01", "count": 10}))
 | Tool | Reads | Credits |
 |---|---|---|
 | `x_search_tweets` | Search with the x.com operators | 1 per result |
-| `x_get_user` | One profile | 1 |
-| `x_get_users` | Up to 100 profiles in one call | 1 per profile |
+| `x_get_user` | One profile, by `handle` or by numeric user `id` | 1 |
+| `x_get_users` | Up to 100 profiles in one call, by `handles` or by `ids` | 1 per profile |
 | `x_get_user_tweets` | Latest posts of a user | 1 per post |
 | `x_get_tweet` | One post | 1 |
 | `x_get_tweets` | Up to 100 posts in one call | 1 per post |

{langchain_xdataapi-0.1.0 → langchain_xdataapi-0.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "langchain-xdataapi"
-version = "0.1.0"
+version = "0.1.1"
 description = "LangChain tools for xdataapi.io: read-only public X (Twitter) profiles, tweets, threads, followers and search."
 readme = "README.md"
 license = "MIT"

{langchain_xdataapi-0.1.0 → langchain_xdataapi-0.1.1}/src/langchain_xdataapi/tools.py

@@ -11,7 +11,7 @@ from typing import Any, Literal, Sequence
 
 from langchain_core.callbacks import AsyncCallbackManagerForToolRun, CallbackManagerForToolRun
 from langchain_core.tools import BaseTool
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 from .client import XdataapiClient
 
@@ -47,39 +47,78 @@ class _Base(BaseTool):
 # --- users ---------------------------------------------------------------
 
 
+def _one_of(first: Any, second: Any, names: str) -> None:
+    """A user is named by handle or by id, never by both and never by neither."""
+    if (first is None) == (second is None):
+        raise ValueError(f"give {names}, one of the two")
+
+
 class _UserArgs(BaseModel):
-    handle: str = Field(description="X handle, with or without the leading @.")
+    handle: str | None = Field(default=None, description="X handle, with or without the leading @.")
+    id: str | None = Field(
+        default=None,
+        pattern=r"^\d{1,19}$",
+        description="Numeric user id. It stays the same when the user changes the handle.",
+    )
     fresh: bool | None = Field(default=None, description="Skip the cache. Costs double.")
 
+    @model_validator(mode="after")
+    def _handle_or_id(self) -> "_UserArgs":
+        _one_of(self.handle, self.id, "handle or id")
+        return self
+
 
 class GetUser(_Base):
     name: str = "x_get_user"
     description: str = (
-        "Public profile of one X (Twitter) user by handle: bio, counts, verified state, "
-        "created date. Costs 1 credit."
+        "Public profile of one X (Twitter) user, by handle or by numeric user id (give one of "
+        "the two): bio, counts, verified state, created date. The id stays the same when the "
+        "user changes the handle. Costs 1 credit."
     )
     args_schema: type[BaseModel] = _UserArgs
 
-    def _call(self, handle: str, fresh: bool | None = None) -> tuple[str, dict[str, Any] | None]:
-        return f"/v1/users/{_handle(handle)}", {"fresh": fresh}
+    def _call(
+        self, handle: str | None = None, id: str | None = None, fresh: bool | None = None
+    ) -> tuple[str, dict[str, Any] | None]:
+        _one_of(handle, id, "handle or id")
+        if id is not None:
+            return f"/v1/users/id/{id.strip()}", {"fresh": fresh}
+        return f"/v1/users/{_handle(handle or '')}", {"fresh": fresh}
 
 
 class _UsersArgs(BaseModel):
-    handles: Sequence[str] = Field(description="Up to 100 handles in one call.")
+    handles: Sequence[str] | None = Field(default=None, description="Up to 100 handles in one call.")
+    ids: Sequence[str] | None = Field(
+        default=None, description="Up to 100 numeric user ids in one call, in place of handles."
+    )
     fresh: bool | None = Field(default=None, description="Skip the cache. Costs double.")
 
+    @model_validator(mode="after")
+    def _handles_or_ids(self) -> "_UsersArgs":
+        _one_of(self.handles, self.ids, "handles or ids")
+        return self
+
 
 class GetUsers(_Base):
     name: str = "x_get_users"
     description: str = (
-        "Profiles of up to 100 X users in ONE call. Prefer this over repeated single reads: "
+        "Profiles of up to 100 X users in ONE call, by handle (handles) or by numeric user id "
+        "(ids); give one of the two lists. Prefer this over repeated single reads: "
         "it is one request and one rate-limit slot. Costs 1 credit per profile found; "
-        "handles that do not exist are listed in errors and cost nothing."
+        "inputs that do not exist are listed in errors and cost nothing."
     )
     args_schema: type[BaseModel] = _UsersArgs
 
-    def _call(self, handles: Sequence[str], fresh: bool | None = None) -> tuple[str, dict[str, Any] | None]:
-        return "/v1/users/batch", {"handles": ",".join(_handle(h) for h in handles), "fresh": fresh}
+    def _call(
+        self,
+        handles: Sequence[str] | None = None,
+        ids: Sequence[str] | None = None,
+        fresh: bool | None = None,
+    ) -> tuple[str, dict[str, Any] | None]:
+        _one_of(handles, ids, "handles or ids")
+        if ids is not None:
+            return "/v1/users/batch", {"ids": ",".join(i.strip() for i in ids), "fresh": fresh}
+        return "/v1/users/batch", {"handles": ",".join(_handle(h) for h in handles or []), "fresh": fresh}
 
 
 class _PageArgs(BaseModel):

{langchain_xdataapi-0.1.0 → langchain_xdataapi-0.1.1}/tests/test_tools.py

@@ -8,6 +8,7 @@ from langchain_xdataapi import (
     GetBalance,
     GetTweets,
     GetUser,
+    GetUsers,
     SearchTweets,
     XdataapiAuthError,
     XdataapiClient,
@@ -32,6 +33,41 @@ def test_get_user_strips_the_at_sign():
     assert json.loads(out)["credits_charged"] == 1
 
 
+@respx.mock
+def test_get_user_by_id_reads_the_id_route():
+    route = respx.get(f"{BASE}/v1/users/id/783214").mock(
+        return_value=httpx.Response(200, json={"data": {"id": "783214", "handle": "X"}, "credits_charged": 1})
+    )
+    out = GetUser(client=client()).invoke({"id": "783214"})
+    assert route.called
+    assert json.loads(out)["data"]["handle"] == "X"
+
+
+def test_get_user_wants_a_handle_or_an_id_and_not_both():
+    tool = GetUser(client=client())
+    with pytest.raises(Exception, match="handle or id"):
+        tool.invoke({})
+    with pytest.raises(Exception, match="handle or id"):
+        tool.invoke({"handle": "x", "id": "783214"})
+    with pytest.raises(Exception):
+        tool.invoke({"id": "not-a-number"})
+
+
+@respx.mock
+def test_users_batch_by_ids_sends_ids_and_no_handles():
+    route = respx.get(f"{BASE}/v1/users/batch").mock(return_value=httpx.Response(200, json={"data": []}))
+    GetUsers(client=client()).invoke({"ids": ["783214", "13334762"]})
+    params = route.calls.last.request.url.params
+    assert params["ids"] == "783214,13334762"
+    assert "handles" not in params
+    GetUsers(client=client()).invoke({"handles": ["@x", "github"]})
+    params = route.calls.last.request.url.params
+    assert params["handles"] == "x,github"
+    assert "ids" not in params
+    with pytest.raises(Exception, match="handles or ids"):
+        GetUsers(client=client()).invoke({"handles": ["x"], "ids": ["1"]})
+
+
 @respx.mock
 def test_search_passes_the_operators_through_untouched():
     route = respx.get(f"{BASE}/v1/tweets/search").mock(