15.2.100. camcops_server.cc_modules.cc_client_api_core

camcops_server/cc_modules/cc_client_api_core.py

---

Copyright (C) 2012, University of Cambridge, Department of Psychiatry. Created by Rudolf Cardinal (rnc1001@cam.ac.uk).

This file is part of CamCOPS.

CamCOPS is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

CamCOPS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with CamCOPS. If not, see <https://www.gnu.org/licenses/>.

---

Core constants and functions used by the client (tablet device) API.

class camcops_server.cc_modules.cc_client_api_core.AllowedTablesFieldNames

To match allowedservertable.cpp on the tablet

class camcops_server.cc_modules.cc_client_api_core.BatchDetails(batchtime: Optional[pendulum.datetime.DateTime] = None, preserving: bool = False, onestep: bool = False)

Represents a current upload batch.

__init__(batchtime: Optional[pendulum.datetime.DateTime] = None, preserving: bool = False, onestep: bool = False) → None

Parameters

• batchtime – the batchtime; UTC time this upload batch started; will be applied to all changes

• preserving – are we preserving (finalizing) the records – that is, moving them from the current era (NOW) to the batchtime era, so they can be deleted from the tablet without apparent loss on the server?

• onestep – is this a one-step whole-database upload?

property new_era: str

Returns the string used for the new era for this batch, in case we are preserving records.

class camcops_server.cc_modules.cc_client_api_core.ExtraStringFieldNames

To match extrastring.cpp on the tablet.

exception camcops_server.cc_modules.cc_client_api_core.ServerErrorException

Exception class for when something’s broken on the server side.

class camcops_server.cc_modules.cc_client_api_core.ServerRecord(client_pk: Optional[int] = None, exists_on_server: bool = False, server_pk: Optional[int] = None, server_when: Optional[pendulum.datetime.DateTime] = None, move_off_tablet: bool = False, current: bool = False, addition_pending: bool = False, removal_pending: bool = False, predecessor_pk: Optional[int] = None, successor_pk: Optional[int] = None)

Class to represent whether a server record exists, and/or the results of retrieving server records.

__init__(client_pk: Optional[int] = None, exists_on_server: bool = False, server_pk: Optional[int] = None, server_when: Optional[pendulum.datetime.DateTime] = None, move_off_tablet: bool = False, current: bool = False, addition_pending: bool = False, removal_pending: bool = False, predecessor_pk: Optional[int] = None, successor_pk: Optional[int] = None) → None

Parameters

• client_pk – client’s PK

• exists_on_server – does the record exist on the server?

• server_pk – if it exists, what’s the server PK?

• server_when – if it exists, what’s the server’s “when” (when_last_modified) field?

• move_off_tablet – is the __move_off_tablet flag set?

• current – is the record current (_current flag set)?

• addition_pending – is the _addition_pending flag set?

• removal_pending – is the _removal_pending flag set?

• predecessor_pk – predecessor server PK, or None

• successor_pk – successor server PK, or None

class camcops_server.cc_modules.cc_client_api_core.TabletParam

Keys used by server or client (in the comments: S server, C client, B bidirectional).

class camcops_server.cc_modules.cc_client_api_core.UploadRecordResult(oldserverpk: Optional[int] = None, newserverpk: Optional[int] = None, dirty: bool = False, specifically_marked_for_preservation: bool = False)

Represents the result of uploading a record.

__init__(oldserverpk: Optional[int] = None, newserverpk: Optional[int] = None, dirty: bool = False, specifically_marked_for_preservation: bool = False)

Parameters

• oldserverpk – the server’s PK of the old version of the record; None if the record is new

• newserverpk – the server’s PK of the new version of the record; None if the record was unmodified

• dirty – was the database table modified? (May be true even if newserverpk is None, if _move_off_tablet was set.

• specifically_marked_for_preservation – should the record(s) be preserved?

property addition_pks: List[int]

Returns a list of PKs representing new records being added.

property all_pks: List[int]

Returns all PKs (old, new, or both).

property current_pks: List[int]

Returns PKs that represent current records on the server.

property latest_pk: Optional[int]

Returns the latest of the two PKs.

note_specifically_marked_preservation_pks(pks: List[int]) → None

Notes that some PKs are marked specifically for preservation.

property removal_modified_pks: List[int]

Returns a list of PKs representing records removed because they have been “modified out”.

property specifically_marked_preservation_pks: List[int]

Returns a list of server PKs of records specifically marked to be preserved. This may include older versions (the predecessor chain) of records being uploaded.

class camcops_server.cc_modules.cc_client_api_core.UploadTableChanges(table: sqlalchemy.sql.schema.Table)

Represents information to process and audit an upload to a table.

__init__(table: sqlalchemy.sql.schema.Table) → None

property addition_pks: List[int]

Server PKs of records being added.

property any_changes: bool

Has anything changed that we’re aware of?

description(always_show_current_pks: bool = True) → str

Short description, only including bits that have changed.

get_task_push_export_pks(recipient: ExportRecipient, uploading_group_id: int) → List[int]

Returns PKs for tasks matching the requirements of a particular export recipient.

(In practice, only “push” recipients will come our way, so we can ignore this.)

property idnum_add_index_pks: List[int]

Server PKs of records to add index entries for, if this is the ID number table.

property idnum_delete_index_pks: List[int]

Server PKs of records to delete old index entries for, if this is the ID number table. (Includes records that need re-indexing.)

We don’t care about preservation PKs here, as the ID number index doesn’t incorporate that.

property n_added: int

Number of server records added.

property n_preserved: int

Number of server records “preserved” (finalized) – moved from the NOW era to the batch era (and no longer modifiable by the client device).

property n_removed: int

Number of server records “removed” – marked as removed (either with or without a successor).

property n_removed_deleted: int

Number of server records “deleted” – marked as removed with no successor.

property n_removed_modified: int

Number of server records “modified out” – replaced by a modified version and marked as removed.

note_addition_pk(pk: int) → None

Records an “addition” PK.

note_addition_pks(pks: Iterable[int]) → None

Records multiple “addition” PKs.

note_current_pk(pk: int) → None

Records that a record is current on the server. For indexing.

note_current_pks(pks: Iterable[int]) → None

Records multiple “current” PKs.

note_preservation_pk(pk: int) → None

Records a “preservation” PK (a record that’s being finalized).

note_preservation_pks(pks: Iterable[int]) → None

Records multiple “preservation” PKs (records that are being finalized).

note_removal_deleted_pk(pk: int) → None

Records a “deleted” PK (removed with no successor).

note_removal_deleted_pks(pks: Iterable[int]) → None

Records multiple “deleted” PKs (see note_removal_deleted_pk()).

note_removal_modified_pk(pk: int) → None

Records a “removal because modified” PK (replaced by successor).

note_removal_modified_pks(pks: Iterable[int]) → None

Records multiple “removal because modified” PKs.

note_serverrec(sr: camcops_server.cc_modules.cc_client_api_core.ServerRecord, preserving: bool) → None

Records information from a ServerRecord. Called by camcops_server.cc_modules.client_api.commit_table().

Parameters

• sr – a ServerRecord

• preserving – are we preserving uploaded records?

note_urr(urr: camcops_server.cc_modules.cc_client_api_core.UploadRecordResult, preserving_new_records: bool) → None

Records information from a UploadRecordResult, which is itself the result of calling camcops_server.cc_modules.client_api.upload_record_core().

Called by camcops_server.cc_modules.client_api.process_table_for_onestep_upload().

Parameters

• urr – a UploadRecordResult

• preserving_new_records – are new records being preserved?

property preservation_pks: List[int]

Server PKs of records being preserved.

property removal_deleted_pks: List[int]

Server PKs of records being deleted.

property removal_modified_pks: List[int]

Server PKs of records being modified out.

property removal_pks: List[int]

Server PKs of records being removed (modified out, or deleted).

property tablename: str

The table’s name.

property task_delete_index_pks: List[int]

Server PKs of records to delete old index entries for, if this is a task table. (Includes records that need re-indexing.)

property task_reindex_pks: List[int]

Server PKs of records to rebuild index entries for, if this is a task table. (Includes records that need re-indexing.)

We include records being preserved, because their era has changed, and the index includes era. Unless they are being removed!

exception camcops_server.cc_modules.cc_client_api_core.UserErrorException

Exception class for when the input from the tablet is dodgy.

class camcops_server.cc_modules.cc_client_api_core.WhichKeyToSendInfo(client_pk: int, client_when: pendulum.datetime.DateTime, client_move_off_tablet: bool)

Represents information the client has sent, asking us which records it needs to upload recordwise.

__init__(client_pk: int, client_when: pendulum.datetime.DateTime, client_move_off_tablet: bool) → None

camcops_server.cc_modules.cc_client_api_core.exception_description(e: Exception) → str

Returns a formatted description of a Python exception.

camcops_server.cc_modules.cc_client_api_core.fail_server_error(msg: str) → NoReturn

Function to abort the script when something’s broken server-side.

Raises ServerErrorException.

camcops_server.cc_modules.cc_client_api_core.fail_server_error_from_exception(e: Exception) → NoReturn

Raise ServerErrorException with a description that comes from the specified exception.

camcops_server.cc_modules.cc_client_api_core.fail_unsupported_operation(operation: str) → NoReturn

Abort the script (with a UserErrorException) when the operation is invalid.

camcops_server.cc_modules.cc_client_api_core.fail_user_error(msg: str) → NoReturn

Function to abort the script when the input is dodgy.

Raises UserErrorException.

camcops_server.cc_modules.cc_client_api_core.fail_user_error_from_exception(e: Exception) → NoReturn

Raise UserErrorException with a description that comes from the specified exception.

camcops_server.cc_modules.cc_client_api_core.get_server_live_records(req: CamcopsRequest, device_id: int, table: sqlalchemy.sql.schema.Table, clientpk_name: str = None, current_only: bool = True) → List[camcops_server.cc_modules.cc_client_api_core.ServerRecord]

Gets details of all records on the server, for the specified table, that are live on this client device.

Parameters

• req – the camcops_server.cc_modules.cc_request.CamcopsRequest

• device_id – ID of the camcops_server.cc_modules.cc_device.Device

• table – an SQLAlchemy Table

• clientpk_name – the column name of the client’s PK; if none is supplied, the client_pk fields of the results will be None

• current_only – restrict to “current” (_current) records only?

Returns

ServerRecord objects for active records (_current and in the ‘NOW’ era) for the specified device/table.

camcops_server.cc_modules.cc_client_api_core.require_keys(dictionary: Dict[Any, Any], keys: List[Any]) → None

Ensure that all listed keys are present in the specified dictionary, or raise a UserErrorException.

camcops_server.cc_modules.cc_client_api_core.values_delete_later() → Dict[str, Any]

Field/value pairs to mark a record as “to be deleted later”.

camcops_server.cc_modules.cc_client_api_core.values_delete_now(req: CamcopsRequest, batchdetails: camcops_server.cc_modules.cc_client_api_core.BatchDetails) → Dict[str, Any]

Field/value pairs to mark a record as deleted now.

camcops_server.cc_modules.cc_client_api_core.values_preserve_now(req: CamcopsRequest, batchdetails: camcops_server.cc_modules.cc_client_api_core.BatchDetails, forcibly_preserved: bool = False) → Dict[str, Any]

Field/value pairs to mark a record as preserved now.