14.2.55. camcops_server.cc_modules.cc_client_api_core

camcops_server/cc_modules/cc_client_api_core.py


Copyright (C) 2012-2019 Rudolf Cardinal (rudolf@pobox.com).

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 <http://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[source]

To match allowedservertable.cpp on the tablet

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

Represents a current upload batch.

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?
new_era

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[source]

To match extrastring.cpp on the tablet.

exception camcops_server.cc_modules.cc_client_api_core.IgnoringAntiqueTableException[source]

Special exception to return success when we’re ignoring an old tablet’s request to upload the “storedvars” table.

exception camcops_server.cc_modules.cc_client_api_core.ServerErrorException[source]

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

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

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

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[source]

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: Union[int, NoneType] = None, newserverpk: Union[int, NoneType] = None, dirty: bool = False, specifically_marked_for_preservation: bool = False)[source]

Represents the result of uploading a record.

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?
addition_pks

Returns a list of PKs representing new records being added.

all_pks

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

current_pks

Returns PKs that represent current records on the server.

latest_pk

Returns the latest of the two PKs.

note_specifically_marked_preservation_pks(pks: List[int]) → None[source]

Notes that some PKs are marked specifically for preservation.

removal_modified_pks

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

specifically_marked_preservation_pks

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)[source]

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

addition_pks

Server PKs of records being added.

any_changes

Has anything changed that we’re aware of?

description(always_show_current_pks: bool = True) → str[source]

Short description, only including bits that have changed.

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

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.)

idnum_add_index_pks

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

idnum_delete_index_pks

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.

n_added

Number of server records added.

n_preserved

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

n_removed

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

n_removed_deleted

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

n_removed_modified

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

note_addition_pk(pk: int) → None[source]

Records an “addition” PK.

note_addition_pks(pks: Iterable[int]) → None[source]

Records multiple “addition” PKs.

note_current_pk(pk: int) → None[source]

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

note_current_pks(pks: Iterable[int]) → None[source]

Records multiple “current” PKs.

note_preservation_pk(pk: int) → None[source]

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

note_preservation_pks(pks: Iterable[int]) → None[source]

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

note_removal_deleted_pk(pk: int) → None[source]

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

note_removal_deleted_pks(pks: Iterable[int]) → None[source]

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

note_removal_modified_pk(pk: int) → None[source]

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

note_removal_modified_pks(pks: Iterable[int]) → None[source]

Records multiple “removal because modified” PKs.

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

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[source]

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?
preservation_pks

Server PKs of records being preserved.

removal_deleted_pks

Server PKs of records being deleted.

removal_modified_pks

Server PKs of records being modified out.

removal_pks

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

tablename

The table’s name.

task_delete_index_pks

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

task_reindex_pks

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[source]

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)[source]

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

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

Returns a formatted description of a Python exception.

camcops_server.cc_modules.cc_client_api_core.fail_server_error(msg: str) → None[source]

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) → None[source]

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

camcops_server.cc_modules.cc_client_api_core.fail_unsupported_operation(operation: str) → None[source]

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

camcops_server.cc_modules.cc_client_api_core.fail_user_error(msg: str) → None[source]

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) → None[source]

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][source]

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

Parameters:
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[source]

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][source]

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][source]

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][source]

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