From b25889681aa9c055e5801fefbf38acdfd876d03a Mon Sep 17 00:00:00 2001 From: sanderland <48946947+sanderland@users.noreply.github.com> Date: Thu, 3 Oct 2019 10:35:57 +0200 Subject: [PATCH] release v1.3 with non-experimental sequences (#563) --- CHANGELOG.md | 3 + cognite/client/__init__.py | 2 +- cognite/client/_api/sequences.py | 44 +++--- cognite/client/_cognite_client.py | 2 + cognite/client/experimental.py | 2 - cognite/client/testing.py | 3 + docs/source/cognite.rst | 125 +++++++++--------- tests/conftest.py | 4 +- .../test_api/test_sequences.py | 3 +- .../test_api/test_sequences_data.py | 1 - tests/tests_unit/test_api/test_sequences.py | 2 +- tests/tests_unit/test_docstring_examples.py | 6 +- 12 files changed, 97 insertions(+), 100 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2cef3b48b0..77f46b61f6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,7 +20,10 @@ Changes are grouped as follows - Separate read/write fields on data classes ## [Unreleased] + +## [1.3.0] - 2019-10-03 ### Changed +- Sequences officially released and no longer considered experimental. - Sequences data insert no longer takes a default value for columns. ## [1.2.1] - 2019-10-01 diff --git a/cognite/client/__init__.py b/cognite/client/__init__.py index c0762ddbdb..961e86f8f3 100644 --- a/cognite/client/__init__.py +++ b/cognite/client/__init__.py @@ -1,3 +1,3 @@ from cognite.client._cognite_client import CogniteClient -__version__ = "1.2.1" +__version__ = "1.3.0" diff --git a/cognite/client/_api/sequences.py b/cognite/client/_api/sequences.py index e7de45f67e..aa0ceefe39 100644 --- a/cognite/client/_api/sequences.py +++ b/cognite/client/_api/sequences.py @@ -5,10 +5,8 @@ from cognite.client import utils from cognite.client._api_client import APIClient from cognite.client.data_classes import Sequence, SequenceData, SequenceFilter, SequenceList, SequenceUpdate -from cognite.client.utils._experimental_warning import experimental_api -@experimental_api(api_name="Sequences") class SequencesAPI(APIClient): _RESOURCE_PATH = "/sequences" _LIST_CLASS = SequenceList @@ -82,13 +80,13 @@ def retrieve(self, id: Optional[int] = None, external_id: Optional[str] = None) Get sequences by id:: - >>> from cognite.client.experimental import CogniteClient + >>> from cognite.client import CogniteClient >>> c = CogniteClient() >>> res = c.sequences.retrieve(id=1) Get sequences by external id:: - >>> from cognite.client.experimental import CogniteClient + >>> from cognite.client import CogniteClient >>> c = CogniteClient() >>> res = c.sequences.retrieve(external_id="1") """ @@ -111,13 +109,13 @@ def retrieve_multiple( Get sequences by id:: - >>> from cognite.client.experimental import CogniteClient + >>> from cognite.client import CogniteClient >>> c = CogniteClient() >>> res = c.sequences.retrieve_multiple(ids=[1, 2, 3]) Get sequences by external id:: - >>> from cognite.client.experimental import CogniteClient + >>> from cognite.client import CogniteClient >>> c = CogniteClient() >>> res = c.sequences.retrieve_multiple(external_ids=["abc", "def"]) """ @@ -158,20 +156,20 @@ def list( List sequences:: - >>> from cognite.client.experimental import CogniteClient + >>> from cognite.client import CogniteClient >>> c = CogniteClient() >>> res = c.sequences.list(limit=5) Iterate over sequences:: - >>> from cognite.client.experimental import CogniteClient + >>> from cognite.client import CogniteClient >>> c = CogniteClient() >>> for seq in c.sequences: ... seq # do something with the sequences Iterate over chunks of sequences to reduce memory load:: - >>> from cognite.client.experimental import CogniteClient + >>> from cognite.client import CogniteClient >>> c = CogniteClient() >>> for seq_list in c.sequences(chunk_size=2500): ... seq_list # do something with the sequences @@ -205,7 +203,7 @@ def create(self, sequence: Union[Sequence, List[Sequence]]) -> Union[Sequence, S Create a new sequence:: - >>> from cognite.client.experimental import CogniteClient + >>> from cognite.client import CogniteClient >>> from cognite.client.data_classes import Sequence >>> c = CogniteClient() >>> column_def = [{"valueType":"STRING","externalId":"user","description":"some description"}, {"valueType":"DOUBLE","externalId":"amount"}] @@ -250,7 +248,7 @@ def delete(self, id: Union[int, List[int]] = None, external_id: Union[str, List[ Delete sequences by id or external id:: - >>> from cognite.client.experimental import CogniteClient + >>> from cognite.client import CogniteClient >>> c = CogniteClient() >>> c.sequences.delete(id=[1,2,3], external_id="3") """ @@ -271,7 +269,7 @@ def update( Update a sequence that you have fetched. This will perform a full update of the sequences:: - >>> from cognite.client.experimental import CogniteClient + >>> from cognite.client import CogniteClient >>> c = CogniteClient() >>> res = c.sequences.retrieve(id=1) >>> res.description = "New description" @@ -279,7 +277,7 @@ def update( Perform a partial update on a sequence, updating the description and adding a new field to metadata:: - >>> from cognite.client.experimental import CogniteClient + >>> from cognite.client import CogniteClient >>> from cognite.client.data_classes import SequenceUpdate >>> c = CogniteClient() >>> my_update = SequenceUpdate(id=1).description.set("New description").metadata.add({"key": "value"}) @@ -312,7 +310,7 @@ def search( Search for a sequence:: - >>> from cognite.client.experimental import CogniteClient + >>> from cognite.client import CogniteClient >>> c = CogniteClient() >>> res = c.sequences.search(name="some name") """ @@ -357,7 +355,7 @@ def insert( Examples: Your rows of data can be a list of tuples where the first element is the rownumber and the second element is the data to be inserted:: - >>> from cognite.client.experimental import CogniteClient + >>> from cognite.client import CogniteClient >>> c = CogniteClient() >>> seq = c.sequences.create(Sequence(columns=[{"valueType": "STRING", "externalId":"col_a"},{"valueType": "DOUBLE", "externalId":"col_b"}])) >>> data = [(1, ['pi',3.14]), (2, ['e',2.72]) ] @@ -365,21 +363,21 @@ def insert( They can also be provided as a list of API-style objects with a rowNumber and values field:: - >>> from cognite.client.experimental import CogniteClient + >>> from cognite.client import CogniteClient >>> c = CogniteClient() >>> data = [{"rowNumber": 123, "values": ['str',3]}, {"rowNUmber": 456, "values": ["bar",42]} ] >>> c.sequences.data.insert(data, id=1, column_external_ids=["col_a","col_b"]) # implicit columns are retrieved from metadata Or they can be a given as a dictionary with row number as the key, and the value is the data to be inserted at that row:: - >>> from cognite.client.experimental import CogniteClient + >>> from cognite.client import CogniteClient >>> c = CogniteClient() >>> data = {123 : ['str',3], 456 : ['bar',42] } >>> c.sequences.data.insert(column_external_ids=['stringColumn','intColumn'], rows=data, id=1) Finally, they can be a SequenceData object retrieved from another request. In this case column_external_ids from this object are used as well. - >>> from cognite.client.experimental import CogniteClient + >>> from cognite.client import CogniteClient >>> c = CogniteClient() >>> data = c.sequences.data.retrieve(id=2,start=0,end=10) >>> c.sequences.data.insert(rows=data, id=1,column_external_ids=None) @@ -429,7 +427,7 @@ def insert_dataframe( Examples: Multiply data in the sequence by 2:: - >>> from cognite.client.experimental import CogniteClient + >>> from cognite.client import CogniteClient >>> c = CogniteClient() >>> df = c.sequences.data.retrieve_dataframe(id=123, start=0, end=None) >>> c.sequences.data.insert_dataframe(df*2, id=123, external_id_headers=True) @@ -455,7 +453,7 @@ def delete(self, rows: List[int], id: int = None, external_id: str = None) -> No Examples: - >>> from cognite.client.experimental import CogniteClient + >>> from cognite.client import CogniteClient >>> c = CogniteClient() >>> c.sequences.data.delete(id=0, rows=[1,2,42]) """ @@ -480,7 +478,7 @@ def delete_range(self, start: int, end: Union[int, None], id: int = None, extern Examples: - >>> from cognite.client.experimental import CogniteClient + >>> from cognite.client import CogniteClient >>> c = CogniteClient() >>> c.sequences.data.delete_range(id=0, start=0, end=None) """ @@ -518,7 +516,7 @@ def retrieve( Examples: - >>> from cognite.client.experimental import CogniteClient + >>> from cognite.client import CogniteClient >>> c = CogniteClient() >>> res = c.sequences.data.retrieve(id=0, start=0, end=None) >>> tuples = [(r,v) for r,v in res.items()] # You can use this iterator in for loops and list comprehensions, @@ -561,7 +559,7 @@ def retrieve_dataframe( Examples: - >>> from cognite.client.experimental import CogniteClient + >>> from cognite.client import CogniteClient >>> c = CogniteClient() >>> df = c.sequences.data.retrieve_dataframe(id=0, start=0, end=None) """ diff --git a/cognite/client/_cognite_client.py b/cognite/client/_cognite_client.py index 14d865ef6e..1fade84b4b 100644 --- a/cognite/client/_cognite_client.py +++ b/cognite/client/_cognite_client.py @@ -9,6 +9,7 @@ from cognite.client._api.iam import IAMAPI from cognite.client._api.login import LoginAPI from cognite.client._api.raw import RawAPI +from cognite.client._api.sequences import SequencesAPI from cognite.client._api.three_d import ThreeDAPI from cognite.client._api.time_series import TimeSeriesAPI from cognite.client._api_client import APIClient @@ -68,6 +69,7 @@ def __init__( self.events = EventsAPI(self._config, api_version=self._API_VERSION, cognite_client=self) self.files = FilesAPI(self._config, api_version=self._API_VERSION, cognite_client=self) self.iam = IAMAPI(self._config, api_version=self._API_VERSION, cognite_client=self) + self.sequences = SequencesAPI(self._config, api_version=self._API_VERSION, cognite_client=self) self.time_series = TimeSeriesAPI(self._config, api_version=self._API_VERSION, cognite_client=self) self.raw = RawAPI(self._config, api_version=self._API_VERSION, cognite_client=self) self.three_d = ThreeDAPI(self._config, api_version=self._API_VERSION, cognite_client=self) diff --git a/cognite/client/experimental.py b/cognite/client/experimental.py index ab27f81ecb..5571b6ea08 100644 --- a/cognite/client/experimental.py +++ b/cognite/client/experimental.py @@ -1,12 +1,10 @@ from cognite.client._api.model_hosting import ModelHostingAPI from cognite.client._api.relationships import RelationshipsAPI -from cognite.client._api.sequences import SequencesAPI from cognite.client._cognite_client import CogniteClient as Client class CogniteClient(Client): def __init__(self, *args, **kwargs): super().__init__(*args, **kwargs) - self.sequences = SequencesAPI(self._config, api_version=self._API_VERSION, cognite_client=self) self.model_hosting = ModelHostingAPI(self._config, api_version="0.6", cognite_client=self) self.relationships = RelationshipsAPI(self._config, api_version="playground", cognite_client=self) diff --git a/cognite/client/testing.py b/cognite/client/testing.py index f9194bc83d..058f2c1232 100644 --- a/cognite/client/testing.py +++ b/cognite/client/testing.py @@ -9,6 +9,7 @@ from cognite.client._api.iam import IAMAPI, APIKeysAPI, GroupsAPI, SecurityCategoriesAPI, ServiceAccountsAPI from cognite.client._api.login import LoginAPI from cognite.client._api.raw import RawAPI, RawDatabasesAPI, RawRowsAPI, RawTablesAPI +from cognite.client._api.sequences import SequencesAPI, SequencesDataAPI from cognite.client._api.three_d import ( ThreeDAPI, ThreeDAssetMappingAPI, @@ -50,6 +51,8 @@ def __init__(self, *args, **kwargs): self.raw.databases = MagicMock(spec_set=RawDatabasesAPI) self.raw.tables = MagicMock(spec_set=RawTablesAPI) self.raw.rows = MagicMock(spec_set=RawRowsAPI) + self.sequences = MagicMock(spec=SequencesAPI) + self.sequences.data = MagicMock(spec_set=SequencesDataAPI) @contextmanager diff --git a/docs/source/cognite.rst b/docs/source/cognite.rst index 6be60849bc..93bb0958d6 100644 --- a/docs/source/cognite.rst +++ b/docs/source/cognite.rst @@ -478,6 +478,66 @@ Data classes :members: :show-inheritance: +Sequences +--------- + +Retrieve a sequence by id +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesAPI.retrieve + +Retrieve multiple sequences by id +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesAPI.retrieve_multiple + +List sequences +^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesAPI.list + +Search for sequences +^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesAPI.search + +Create a sequence +^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesAPI.create + +Delete sequences +^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesAPI.delete + +Update sequences +^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesAPI.update + +Retrieve data +^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesDataAPI.retrieve + +Retrieve pandas dataframe +^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesDataAPI.retrieve_dataframe + +Insert rows into a sequence +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesDataAPI.insert + +Insert a pandas dataframe into a sequence +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesDataAPI.insert_dataframe + +Delete rows from a sequence +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesDataAPI.delete + +Delete a range of rows from a sequence +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesDataAPI.delete_range + +Data classes +^^^^^^^^^^^^ +.. automodule:: cognite.client.data_classes.sequences + :members: + :show-inheritance: Raw --- @@ -971,71 +1031,6 @@ Data classes :members: :show-inheritance: - -Sequences ---------- -.. WARNING:: - The sequences API is experimental and subject to breaking changes. It should not be used in production code. - -Retrieve a sequence by id -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesAPI.retrieve - -Retrieve multiple sequences by id -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesAPI.retrieve_multiple - -List sequences -^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesAPI.list - -Search for sequences -^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesAPI.search - -Create a sequence -^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesAPI.create - -Delete sequences -^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesAPI.delete - -Update sequences -^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesAPI.update - -Retrieve data -^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesDataAPI.retrieve - -Retrieve pandas dataframe -^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesDataAPI.retrieve_dataframe - -Insert rows into a sequence -^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesDataAPI.insert - -Insert a pandas dataframe into a sequence -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesDataAPI.insert_dataframe - -Delete rows from a sequence -^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesDataAPI.delete - -Delete a range of rows from a sequence -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesDataAPI.delete_range - -Data classes -^^^^^^^^^^^^ -.. automodule:: cognite.client.data_classes.sequences - :members: - :show-inheritance: - - Relationships ------------- .. WARNING:: diff --git a/tests/conftest.py b/tests/conftest.py index 712936b0be..6fad355e11 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -58,6 +58,8 @@ def mock_cognite_client(): cog_client_mock.iam.api_keys = mock.MagicMock(spec=APIKeysAPI) cog_client_mock.iam.groups = mock.MagicMock(spec=GroupsAPI) cog_client_mock.iam.security_categories = mock.MagicMock(spec=SecurityCategoriesAPI) + cog_client_mock.sequences = mock.MagicMock(spec=SequencesAPI) + cog_client_mock.sequences.data = mock.MagicMock(spec=SequencesDataAPI) raw_mock = mock.MagicMock(spec=RawAPI) raw_mock.databases = mock.MagicMock(spec=RawDatabasesAPI) raw_mock.tables = mock.MagicMock(spec=RawTablesAPI) @@ -72,8 +74,6 @@ def mock_cognite_experimental_client(mock_cognite_client): with mock.patch("cognite.client.experimental.CogniteClient") as client_mock: cog_client_mock = mock.MagicMock(spec=CogniteClient) cog_client_mock.assets = mock.MagicMock(spec=AssetsAPI) - cog_client_mock.sequences = mock.MagicMock(spec=SequencesAPI) - cog_client_mock.sequences.data = mock.MagicMock(spec=SequencesDataAPI) cog_client_mock.relationships = mock.MagicMock(spec=RelationshipsAPI) client_mock.return_value = cog_client_mock yield diff --git a/tests/tests_integration/test_api/test_sequences.py b/tests/tests_integration/test_api/test_sequences.py index ad90af7f15..ab69d33570 100644 --- a/tests/tests_integration/test_api/test_sequences.py +++ b/tests/tests_integration/test_api/test_sequences.py @@ -3,10 +3,9 @@ import pytest -from cognite.client import utils +from cognite.client import CogniteClient, utils from cognite.client.data_classes import Sequence, SequenceFilter, SequenceUpdate from cognite.client.exceptions import CogniteAPIError -from cognite.client.experimental import CogniteClient from tests.utils import set_request_limit COGNITE_CLIENT = CogniteClient() diff --git a/tests/tests_integration/test_api/test_sequences_data.py b/tests/tests_integration/test_api/test_sequences_data.py index efcdd4c0a2..a34c78d366 100644 --- a/tests/tests_integration/test_api/test_sequences_data.py +++ b/tests/tests_integration/test_api/test_sequences_data.py @@ -8,7 +8,6 @@ from cognite.client import CogniteClient, utils from cognite.client.data_classes import Sequence, SequenceData -from cognite.client.experimental import CogniteClient from tests.utils import set_request_limit COGNITE_CLIENT = CogniteClient() diff --git a/tests/tests_unit/test_api/test_sequences.py b/tests/tests_unit/test_api/test_sequences.py index 7e4536f4bd..bc53f303ec 100644 --- a/tests/tests_unit/test_api/test_sequences.py +++ b/tests/tests_unit/test_api/test_sequences.py @@ -6,8 +6,8 @@ import pytest +from cognite.client import CogniteClient from cognite.client.data_classes import Sequence, SequenceData, SequenceFilter, SequenceList, SequenceUpdate -from cognite.client.experimental import CogniteClient from tests.utils import jsgz_load COGNITE_CLIENT = CogniteClient() diff --git a/tests/tests_unit/test_docstring_examples.py b/tests/tests_unit/test_docstring_examples.py index cb06a24252..a896af6bd1 100644 --- a/tests/tests_unit/test_docstring_examples.py +++ b/tests/tests_unit/test_docstring_examples.py @@ -60,11 +60,11 @@ def test_3d(self): def test_iam(self): run_docstring_tests(iam) - -@pytest.mark.usefixtures("mock_cognite_experimental_client") -class TestDocstringExamplesExperimental: def test_sequences(self): run_docstring_tests(sequences) + +@pytest.mark.usefixtures("mock_cognite_experimental_client") +class TestDocstringExamplesExperimental: def test_relationships(self): run_docstring_tests(relationships)