From 391b344637baf08ebedeb5c43fce64ffdd3d66f9 Mon Sep 17 00:00:00 2001 From: Mark Hadley Date: Tue, 14 Aug 2018 16:17:16 -0600 Subject: [PATCH] Update Documentation for Wrappers (#445) * Adds Documentation Steps for Node * Adds generate Docs for Python * Updates python gitignore * Adds documentation for Connection and vcx init for both wrappers * Updates All Node Wrapper Functions for Documentation * Updates All Python Wrapper Functions for Documentation * Fixes Description for Proof.create Function * Updates per Review Comments * Ignore Mocked Accepted Connection Test for Node * Updates Docs * Adds Script for Generating Python Docs Signed-off-by: Mark Hadley --- vcx/wrappers/node/README.md | 11 + vcx/wrappers/node/package.json | 3 +- vcx/wrappers/node/src/api/connection.ts | 80 +++-- vcx/wrappers/node/src/api/credential-def.ts | 66 +++-- vcx/wrappers/node/src/api/credential.ts | 3 +- vcx/wrappers/node/src/api/init.ts | 32 ++ vcx/wrappers/node/src/api/schema.ts | 100 +++++-- vcx/wrappers/node/src/api/utils.ts | 19 ++ vcx/wrappers/node/src/api/wallet.ts | 275 ++++++++++++------ vcx/wrappers/python3/.gitignore | 3 + vcx/wrappers/python3/README.md | 11 + vcx/wrappers/python3/generate_docs.py | 42 +++ vcx/wrappers/python3/vcx/api/connection.py | 33 ++- .../python3/vcx/api/credential_def.py | 53 +++- vcx/wrappers/python3/vcx/api/proof.py | 5 +- vcx/wrappers/python3/vcx/api/schema.py | 51 ++++ vcx/wrappers/python3/vcx/api/utils.py | 40 +++ vcx/wrappers/python3/vcx/api/vcx_init.py | 28 ++ vcx/wrappers/python3/vcx/api/wallet.py | 186 ++++++++++++ 19 files changed, 843 insertions(+), 198 deletions(-) create mode 100644 vcx/wrappers/python3/generate_docs.py diff --git a/vcx/wrappers/node/README.md b/vcx/wrappers/node/README.md index 40af429c16..cf753699ca 100644 --- a/vcx/wrappers/node/README.md +++ b/vcx/wrappers/node/README.md @@ -1,3 +1,4 @@ + # VCX NodeJS Wrapper ## Contribution Guide @@ -18,3 +19,13 @@ Run this commands before submitting your PR: ``` npm run lint ``` + +## Documentation: + Run these commands: +``` +npm install +npm ci +npm doc-gen +``` +* A directory will be created locally `./docs` which contains an `index.html` file which can be used to navigate the generated documents. + diff --git a/vcx/wrappers/node/package.json b/vcx/wrappers/node/package.json index 92ccb25a82..1d68d0f10d 100644 --- a/vcx/wrappers/node/package.json +++ b/vcx/wrappers/node/package.json @@ -36,7 +36,7 @@ "scripts": { "compile": "./node_modules/.bin/tsc -p ./tsconfig.json", "lint": "./node_modules/.bin/tslint --type-check -c ./tslint.json -p ./tsconfig.json && ./node_modules/.bin/tslint --type-check -c ./test/tslint.json -p ./test/tsconfig.json", - "doc-gen": "./node_modules/.bin/jsdoc -r -d doc dist/*", + "doc-gen": "./node_modules/.bin/typedoc --out doc --excludePrivate --excludeProtected --ignoreCompilerErrors src", "test": "export TS_NODE_PROJECT=\"./test/tsconfig.json\" export NODE_ENV='test' && export RUST_LOG=\"trace\" && export RUST_BACKTRACE=full && ./node_modules/.bin/mocha --timeout 10000 -gc --expose-gc --exit --recursive --use_strict --require ts-node/register ./test/suite1/**/*.test.ts && ./node_modules/.bin/mocha --timeout 10000 -gc --expose-gc --exit --recursive --use_strict --require ts-node/register ./test/suite2/**/*.test.ts" }, "devDependencies": { @@ -53,6 +53,7 @@ "ts-node": "^6.1.2", "tslint": "^5.8.0", "tslint-config-standard": "^7.1.0", + "typedoc": "0.11.1", "typescript": "^2.9.1" }, "main": "dist/index.js", diff --git a/vcx/wrappers/node/src/api/connection.ts b/vcx/wrappers/node/src/api/connection.ts index f5dea7ea84..8c130223eb 100644 --- a/vcx/wrappers/node/src/api/connection.ts +++ b/vcx/wrappers/node/src/api/connection.ts @@ -42,15 +42,14 @@ export interface IConnectOptions { */ export class Connection extends VCXBaseWithState { /** - * @memberof Connection - * @description Builds a generic Connection object. - * @static - * @async - * @function create - * @param {IConnectionCreateData} recipientInfo - * @example Example of recipientInfo - * {id: "123"} - * @returns {Promise} A Connection Object + * Create a connection object, represents a single endpoint and can be used for sending and receiving + * credentials and proofs + * + * Example: + * ``` + * source_id = 'foobar123' + * connection = await Connection.create(source_id) + * ``` */ public static async create ({ id }: IConnectionCreateData): Promise { try { @@ -64,15 +63,15 @@ export class Connection extends VCXBaseWithState { } /** - * @memberof Connection - * @description Builds a generic Connection object. - * @static - * @async - * @function create - * @param {IConnectionCreateData} recipientInfo - * @example Example of recipientInfo - * {id: "123"} - * @returns {Promise} A Connection Object + * Create a connection object with a provided invite, represents a single endpoint and can be used for + * sending and receiving credentials and proofs. + * Invite details are provided by the entity offering a connection and generally pulled from a provided QRCode. + * + * Example: + * ``` + * sourceId = 'foobar123' + * connection_handle = await Connection.createWithInvite({sourceId, inviteDetails}) + * ``` */ public static async createWithInvite ({ id, invite }: IRecipientInviteInfo): Promise { const connection = new Connection(id) @@ -88,18 +87,10 @@ export class Connection extends VCXBaseWithState { } /** - * @memberof Connection - * @description Builds a Connection object with defined attributes. - * The attributes are often provided by a previous call to the serialize function - * @static - * @async - * @function deserialize - * @param {ISerializedData} connectionData - contains the information - * that will be used to build a connection object - * @example Example of Connection Data - * {source_id:"234",handle:560373036,pw_did:"did",pw_verkey:"verkey",did_endpoint:"",state:2,uuid:"",endpoint:"", - * invite_detail:{e:"",rid:"",sakdp:"",sn:"",sD:"",lu:"",sVk:"",tn:""}} - * @returns {Promise} A Connection Object + * Create the object from a previously serialized object. + * Example: + * data = await connection1.serialize() + * connection2 = await Connection.deserialize(data) */ public static async deserialize (connectionData: ISerializedData) { const connection = await super._deserialize(Connection, connectionData) @@ -114,10 +105,13 @@ export class Connection extends VCXBaseWithState { protected _inviteDetailFn = rustAPI().vcx_connection_invite_details /** - * @memberof Connection - * @description Deletes and releases a connection - * @function delete - * @returns {Promis} + * Delete the object from the agency and release any memory associated with it + * + * Example: + * ``` + * def connection = await Connection.create(source_id) + * await connection.delete() + * ``` */ public async delete (): Promise { try { @@ -148,8 +142,9 @@ export class Connection extends VCXBaseWithState { * * Example: * ``` - * connection = await Connection.create({id: 'foobar'}) - * inviteDetails = await connection.connect() + * phoneNumber = '8019119191' + * connection = await Connection.create('foobar123') + * inviteDetails = await connection.connect({phone: phoneNumber}) * ``` * @returns {Promise { } /** - * @memberof Connection - * @description * Gets the details of the invitation that was returned from the Agent Service. - * @async - * @function inviteDetails - * @returns {Promise} - String with the details + * + * Example: + * ``` + * phoneNumber = '8019119191' + * connection = await Connection.create('foobar123') + * inviteDetails = await connection.connect({phone: phoneNumber}) + * inivteDetailsAgain = await connection.inviteDetails() + * ``` */ public async inviteDetails (abbr: boolean = false): Promise { try { diff --git a/vcx/wrappers/node/src/api/credential-def.ts b/vcx/wrappers/node/src/api/credential-def.ts index 2e75112bfc..55edf7275a 100644 --- a/vcx/wrappers/node/src/api/credential-def.ts +++ b/vcx/wrappers/node/src/api/credential-def.ts @@ -51,21 +51,19 @@ export class CredentialDefPaymentManager extends PaymentManager { */ export class CredentialDef extends VCXBase { /** - * @memberof CredentialDef - * creates a credential definition on the ledger and returns an associated object. - * @static - * @async - * @function create - * @param {ICredentialDefCreateData} data - * @example Example of ICredentialDefinition - * { - * sourceId: "12", - * schemaId: "2hoqvcwupRTUNkXn6ArYzs:2:test-licence:4.4.4", - * name: "test-licence", - * revocation: false, - * paymentHandle: 0 + * Creates a new CredentialDef object that is written to the ledger + * + * Example: + * ``` + * data = { + * name: 'testCredentialDefName', + * paymentHandle: 0, + * revocation: false, + * schemaId: 'testCredentialDefSchemaId', + * sourceId: 'testCredentialDefSourceId' * } - * @returns {Promise} A credentialDef Object + * credentialDef = await CredentialDef.create(data) + * ``` */ public static async create ({ name, @@ -96,15 +94,21 @@ export class CredentialDef extends VCXBase { } /** - * @memberof CredentialDef - * @description Builds a credentialDef object with defined attributes. + * Builds a credentialDef object with defined attributes. * Attributes are provided by a previous call to the serialize function. - * @static - * @async - * @function deserialize - * @param {ISerialziedData} data - data obtained by serialize api. - * Used to build a credentialdef object. - * @returns {Promise} A credentialDef Object + * Example: + * ``` + * data = { + * name: 'testCredentialDefName', + * paymentHandle: 0, + * revocation: false, + * schemaId: 'testCredentialDefSchemaId', + * sourceId: 'testCredentialDefSourceId' + * } + * credentialDef = await CredentialDef.create(data) + * data1 = await credentialDef.serialize() + * credentialDef2 = await CredentialDef.deserialzie(data1) + * ``` */ public static async deserialize (credentialDef: ISerializedData) { // Todo: update the ICredentialDefObj @@ -132,11 +136,19 @@ export class CredentialDef extends VCXBase { } /** - * @memberof CredentialDef - * @description Retrieves the credential definition id associated with the created cred def. - * @async - * @function getCredDefId - * @returns {Promise} - CredDef's Identifier + * Retrieves the credential definition id associated with the created cred def. + * Example: + * ``` + * data = { + * name: 'testCredentialDefName', + * paymentHandle: 0, + * revocation: false, + * schemaId: 'testCredentialDefSchemaId', + * sourceId: 'testCredentialDefSourceId' + * } + * credentialDef = await CredentialDef.create(data) + * id = await credentialDef.getCredDefId() + * ``` */ public async getCredDefId (): Promise { try { diff --git a/vcx/wrappers/node/src/api/credential.ts b/vcx/wrappers/node/src/api/credential.ts index bb16a6035b..7d2ff4fa2b 100644 --- a/vcx/wrappers/node/src/api/credential.ts +++ b/vcx/wrappers/node/src/api/credential.ts @@ -98,6 +98,7 @@ export class Credential extends VCXBaseWithState { } /** + * Create a Credential object that requests and receives a credential for an institution * * ``` * credential = Credential.createWithMsgId({ @@ -106,8 +107,6 @@ export class Credential extends VCXBaseWithState { * sourceId: 'testCredentialSourceId' * }) * ``` - * - * */ public static async createWithMsgId ( { connection, sourceId, msgId }: ICredentialCreateWithMsgId diff --git a/vcx/wrappers/node/src/api/init.ts b/vcx/wrappers/node/src/api/init.ts index b995bf9fb7..74bc333c5e 100644 --- a/vcx/wrappers/node/src/api/init.ts +++ b/vcx/wrappers/node/src/api/init.ts @@ -5,6 +5,15 @@ import { initRustAPI, rustAPI } from '../rustlib' import { createFFICallbackPromise } from '../utils/ffi-helpers' import { IInitVCXOptions } from './common' +/** + * Initializes VCX with config file. + * An example config file is at libvcx/sample_config/config.json + * + * Example: + * ``` + * await initVcx('/home/username/vcxconfig.json') + * ``` + */ export async function initVcx (configPath: string, options: IInitVCXOptions = {}): Promise { initRustAPI(options.libVCXPath) let rc = null @@ -32,6 +41,29 @@ export async function initVcx (configPath: string, options: IInitVCXOptions = {} } } +/** + * Initializes VCX with config file. + * An example config file is at libvcx/sample_config/config.json + * + * Example: + * ``` + * config = { + * "agency_did": "L5nbFwXJRmdnJVYhCsy52j", + * "agency_verkey": "BQEgx9PJ7JJgt1LadyP45a7JrWdyqkrzrCBGRZ9QVrvL", + * "agency_endpoint": "https://cagency.pdev.evernym.com", + * "genesis_path":"/var/lib/indy/verity-staging/pool_transactions_genesis", + * "institution_name": "institution", + * "institution_logo_url": "http://robohash.org/234", + * "institution_did": "EwsFhWVoc3Fwqzrwe998aQ", + * "institution_verkey": "8brs38hPDkw5yhtzyk2tz7zkp8ijTyWnER165zDQbpK6", + * "remote_to_sdk_did": "EtfeMFytvYTKnWwqTScp9D", + * "remote_to_sdk_verkey": "8a7hZDyJK1nNCizRCKMr4H4QbDm8Gg2vcbDRab8SVfsi", + * "sdk_to_remote_did": "KacwZ2ndG6396KXJ9NDDw6", + * "sdk_to_remote_verkey": "B8LgZGxEPcpTJfZkeqXuKNLihM1Awm8yidqsNwYi5QGc" + * } + * await initVcxWithConfig('/home/username/vcxconfig.json') + * ``` + */ export async function initVcxWithConfig (config: string, options: IInitVCXOptions = {}): Promise { initRustAPI(options.libVCXPath) let rc = null diff --git a/vcx/wrappers/node/src/api/schema.ts b/vcx/wrappers/node/src/api/schema.ts index f9b9dca6a9..b7adda1c54 100644 --- a/vcx/wrappers/node/src/api/schema.ts +++ b/vcx/wrappers/node/src/api/schema.ts @@ -65,15 +65,23 @@ export class SchemaPaymentManager extends PaymentManager { export class Schema extends VCXBase { /** - * @memberof Schema - * @description Builds a generic Schema object - * @static - * @async - * @function create - * @param {ISchemaCreateData} data - * @example Example of ISchema - * {sourceId: '123', data: {name: 'name', version: '1.0', attrNames:['name', 'address', 'city']}} - * @returns {Promise} A Schema Object + * Builds a generic Schema object + * + * Example: + * ``` + * data: { + * attrNames: [ + * 'attr1', + * 'attr2' + * ], + * name: 'Schema', + * version: '1.0.0' + * }, + * paymentHandle: 0, + * sourceId: 'testSchemaSourceId' + * } + * schema1 = await Schema.create(data) + * ``` */ public static async create ({ paymentHandle, data, sourceId }: ISchemaCreateData): Promise { try { @@ -96,15 +104,26 @@ export class Schema extends VCXBase { } /** - * @memberof Schema - * @description Builds Schema object with defined attributes. + * Builds Schema object with defined attributes. * Attributes are provided by a previous call to the serialize function. - * @static - * @async - * @function deserialize - * @param {ISerializedData} schema - contains the information that will - * be used to build a Schema object - * @returns {Promise} A Schema Object + * + * Example: + * ``` + * sourceId = 'lookupTest' + * data: { + * attrNames: [ + * 'attr1', + * 'attr2' + * ], + * name: 'Schema', + * version: '1.0.0' + * }, + * paymentHandle: 0, + * sourceId: sourceId + * } + * schema1 = await Schema.create(data) + * data1 = await schema1.serialize() + * schema2 = Schema.deserialize(data1) */ public static async deserialize (schema: ISerializedData) { const { data: { name, schema_id, version, data } } = schema @@ -117,12 +136,26 @@ export class Schema extends VCXBase { } /** - * @memberof Schema - * @description Looks up the attributes of an already created Schema. - * @async - * @function lookup - * @param {obj} data - contains sourceId and schema id - * @returns {Promise} - A schema object with the attributes set + * Looks up the attributes of an already created Schema. + * + * Example: + * ``` + * sourceId = 'lookupTest' + * data: { + * attrNames: [ + * 'attr1', + * 'attr2' + * ], + * name: 'Schema', + * version: '1.0.0' + * }, + * paymentHandle: 0, + * sourceId: sourceId + * } + * schema1 = await Schema.create(data) + * schemaId1 = await schema1.getSchemaId() + * data = await Schema.lookup(sourceId, schemaId1) + * ``` */ public static async lookup ({ sourceId, schemaId }: ISchemaLookupData): Promise { try { @@ -193,7 +226,26 @@ export class Schema extends VCXBase { get name () { return this._name } - + /** + * Get the ledger ID of the object + * + * Example: + * ``` + * data: { + * attrNames: [ + * 'attr1', + * 'attr2' + * ], + * name: 'Schema', + * version: '1.0.0' + * }, + * paymentHandle: 0, + * sourceId: 'testSchemaSourceId' + * } + * schema1 = await Schema.create(data) + * id1 = await schema1.getSchemaId() + * ``` + */ protected async getSchemaId (): Promise { try { const schemaId = await createFFICallbackPromise( diff --git a/vcx/wrappers/node/src/api/utils.ts b/vcx/wrappers/node/src/api/utils.ts index 75d4884477..768452c77a 100644 --- a/vcx/wrappers/node/src/api/utils.ts +++ b/vcx/wrappers/node/src/api/utils.ts @@ -7,6 +7,22 @@ import { IInitVCXOptions } from './common' // import { resolve } from 'url'; export async function provisionAgent (configAgent: string, options: IInitVCXOptions = {}): Promise { + /** + * Provision an agent in the agency, populate configuration and wallet for this agent. + * + * Example: + * ``` + * enterpriseConfig = { + * 'agency_url': 'https://enym-eagency.pdev.evernym.com', + * 'agency_did': 'YRuVCckY6vfZfX9kcQZe3u', + * 'agency_verkey': "J8Yct6FwmarXjrE2khZesUXRVVSVczSoa9sFaGe6AD2v", + * 'wallet_name': 'LIBVCX_SDK_WALLET', + * 'agent_seed': '00000000000000000000000001234561', + * 'enterprise_seed': '000000000000000000000000Trustee1', + * 'wallet_key': '1234' + * } + * vcxConfig = await provisionAgent(JSON.stringify(enterprise_config)) + */ try { initRustAPI(options.libVCXPath) return await createFFICallbackPromise( @@ -62,6 +78,9 @@ export function getVersion (): string { } export async function getLedgerFees (): Promise { + /** + * Get ledger fees from the sovrin network + */ try { const ledgerFees = await createFFICallbackPromise( (resolve, reject, cb) => { diff --git a/vcx/wrappers/node/src/api/wallet.ts b/vcx/wrappers/node/src/api/wallet.ts index 9fa2d184c2..94a08af37b 100644 --- a/vcx/wrappers/node/src/api/wallet.ts +++ b/vcx/wrappers/node/src/api/wallet.ts @@ -82,12 +82,12 @@ export interface IPaymentAddressSeed { export class Wallet { /** - * @memberof Wallet - * @description Gets wallet token info - * @static - * @async - * @param {paymentAddress} address - * @returns {Promise} Wallet info, balance, addresses, etc + * Gets wallet token info + * + * Example: + * ``` + * info = await Wallet.getTokenInfo() + * ``` */ public static async getTokenInfo (handle?: PaymentHandle): Promise { try { @@ -117,12 +117,12 @@ export class Wallet { } /** - * @memberof Wallet - * @description Creates payment address inside wallet - * @static - * @async - * @param - * @returns {Promise} New address + * Creates payment address inside wallet + * + * Example: + * ``` + * address = await Wallet.createPaymentAddress('00000000000000000000000001234567') + * ``` */ public static async createPaymentAddress (seed: IPaymentAddressSeed): Promise { const cSeed = seed.seed ? seed.seed : null @@ -151,12 +151,13 @@ export class Wallet { } /** - * @memberof Wallet - * @description Validates Payment Address - * @static - * @async - * @param - * @returns {Promise} New address + * Validates Payment Address + * + * Example: + * ``` + * address = await Wallet.createPaymentAddress('00000000000000000000000001234567') + * await Wallet.validatePaymentAddress(address) + * ``` */ public static async validatePaymentAddress (paymentAddress: string): Promise { try { @@ -184,12 +185,16 @@ export class Wallet { } /** - * @memberof Wallet - * @description Sends token to a specified address - * @static - * @async - * @param {ISendTokens} sendTokensData - * @returns {Promise} The receipt + * Sends token to a specified address + * + * Example: + * ``` + * address = await Wallet.createPaymentAddress('00000000000000000000000001234567') + * await Wallet.sendTokens({ + * payment: 0, + * recipient: address, + * tokens: 1 + * }) */ public static async sendTokens ({ payment, tokens, recipient }: ISendTokens): Promise { try { @@ -217,9 +222,16 @@ export class Wallet { } /** - * @memberof Wallet - * @description Adds a record to the wallet for storage - * @static + * Adds a record to the wallet for storage + * Example: + * ``` + * await Wallet.addRecord({ + * id: 'RecordId', + * tags: {}, + * type_: 'TestType', + * value: 'RecordValue' + * }) + * ``` * @async * @param {Record} record * @returns {Promise} @@ -254,12 +266,22 @@ export class Wallet { } /** - * @memberof Wallet - * @description Updates a record already in the wallet - * @static - * @async - * @param {Record} record - * @returns {Promise} + * Updates a record already in the wallet + * + * Example: + * ``` + * await Wallet.addRecord({ + * id: 'RecordId', + * tags: {}, + * type_: 'TestType', + * value: 'RecordValue' + * }) + * await Wallet.updateRecordValue({ + * id: 'RecordId', + * type_: 'TestType', + * value: 'RecordValueNew' + * }) + * ``` */ public static async updateRecordValue (record: IRecordUpdate): Promise { const commandHandle = 0 @@ -291,12 +313,24 @@ export class Wallet { } /** - * @memberof Wallet - * @description Updates a record's tags already in the wallet - * @static - * @async - * @param {Record} record - * @returns {Promise} + * Updates a record's tags already in the wallet + * + * Example: + * ``` + * await Wallet.addRecord({ + * id: 'RecordId', + * tags: {}, + * type_: 'TestType', + * value: 'RecordValue' + * }) + * + * updateRecordTags({ + * id: 'RecordId', + * tags: {}, + * type_: 'TestType', + * value: '' + * }) + * ``` */ public static async updateRecordTags (record: IRecord): Promise { const commandHandle = 0 @@ -329,12 +363,27 @@ export class Wallet { } /** - * @memberof Wallet - * @description Adds tags to a record already in the wallet - * @static - * @async - * @param {Record} record - * @returns {Promise} + * Adds tags to a record already in the wallet + * + * Example: + * ``` + * await Wallet.addRecord({ + * id: 'RecordId', + * tags: {}, + * type_: 'TestType', + * value: 'RecordValue' + * }) + * + * addRecordTags({ id: 'RecordId', + * tags: { + * "tagName1": "tag value 1", + * "~tagName2": "tag value 2 unencrypted", + * "tagName3", 1 + * }, + * type_: 'TestType', + * value: '' + * }) + * ``` */ public static async addRecordTags (record: IRecord): Promise { const commandHandle = 0 @@ -367,13 +416,30 @@ export class Wallet { } /** - * @memberof Wallet - * @description Tags to delete from a record already in the wallet - * @static - * @async - * @param {Record} record - * @param {IDeleteRecordTagsOptions} options - * @returns {Promise} + * Tags to delete from a record already in the wallet + * + * Example: + * ``` + * await Wallet.addRecord({ + * id: 'RecordId', + * tags: { + * "foo": "bar", + * "~fizz": "buzz", + * "unencyrptedStringTag": "tag value 1", + * "~encryptedStringTag": "tag value 2 unencrypted", + * "unencyrptedIntTag": 1 + * }, + * type_: 'TestType', + * value: 'RecordValue' + * }) + * + * deleteRecordTags({ + * id: 'RecordId', + * tags: { tagList: [ "foo", "buzz", "~encryptedStringTag" ] } + * type_: 'TestType', + * value: '' + * }) + * ``` */ public static async deleteRecordTags (record: IRecord, { tagList }: IDeleteRecordTagsOptions): Promise { const commandHandle = 0 @@ -406,13 +472,28 @@ export class Wallet { } /** - * @memberof Wallet - * @description Delete a record already in the wallet - * @static - * @async - * @param {Record} record - * @param {List} tagList - * @returns {Promise} + * Delete a record already in the wallet + * + * Example: + * ``` + * await Wallet.addRecord({ + * id: 'RecordId', + * tags: { + * "foo": "bar", + * "~fizz": "buzz", + * "unencyrptedStringTag": "tag value 1", + * "~encryptedStringTag": "tag value 2 unencrypted", + * "unencyrptedIntTag": 1 + * }, + * type_: 'TestType', + * value: 'RecordValue' + * }) + * + * await Wallet.deleteRecord({ + * id: 'RecordId', + * type_: 'TestType' + * }) + * ``` */ public static async deleteRecord ({ type, id }: IDeleteRecordData): Promise { const commandHandle = 0 @@ -444,13 +525,25 @@ export class Wallet { } /** - * @memberof Wallet - * @description Retrieve a record already in the wallet - * @static - * @async - * @param {String} type - * @param {String} id - * @returns {Promise} + * Retrieve a record already in the wallet + * + * Example: + * ``` + * await Wallet.addRecord({ + * id: 'RecordId', + * tags: { + * "foo": "bar", + * "~fizz": "buzz", + * "unencyrptedStringTag": "tag value 1", + * "~encryptedStringTag": "tag value 2 unencrypted", + * "unencyrptedIntTag": 1 + * }, + * type_: 'TestType', + * value: 'RecordValue' + * }) + * + * record = await Wallet.getReocrd({ type: 'TestType', id: 'RecordId'}) + * ``` */ public static async getRecord ({ type, id, options }: IGerRecordData): Promise { const commandHandle = 0 @@ -483,12 +576,12 @@ export class Wallet { } /** - * @memberof Wallet - * @description Open a search handle - * @static - * @async - * @param {IOpenSearchData} searchData - * @returns {Promise} + * Open a search handle + * + * Example: + * ``` + * searchHandle = await openSearch({type: 'TestType'}) + * ``` */ public static async openSearch ({ type, queryJson, options }: IOpenSearchData): Promise { const commandHandle = 0 @@ -521,13 +614,13 @@ export class Wallet { } /** - * @memberof Wallet - * @description Open a search handle - * @static - * @async - * @param {String} type - * @param {String} id - * @returns {Promise} + * Close a search handle + * + * Example: + * ``` + * searchHandle = await Wallet.openSearch({type: 'TestType'}) + * await Wallet.closeSearch(searchHandle) + * ``` */ public static async closeSearch (handle: number): Promise { const commandHandle = 0 @@ -558,13 +651,14 @@ export class Wallet { } /** - * @memberof Wallet - * @description Initiate or continue a search - * @static - * @async - * @param {number} searchHandle - * @param {number} count - * @returns {Promise} + * Initiate or continue a search + * + * Example: + * ``` + * searchHandle = await Wallet.openSearch({type: 'TestType'}) + * records = await Wallet.searchNextRecords(searchHandle, {count:5}) + * await Wallet.closeSearch(searchHandle) + * ``` */ public static async searchNextRecords (handle: number, { count }: ISearchNextRecordsOptions): Promise { const commandHandle = 0 @@ -601,8 +695,13 @@ export class Wallet { * * Example: * ``` - * config: '{"wallet_name":"","wallet_key":"","exported_wallet_path":"","backup_key":""}' - * await Wallet.import(config) + * config = { + * "wallet_name":"", + * "wallet_key":"", + * "exported_wallet_path":"", + * "backup_key":"" + * } + * await Wallet.import(JSON.stringify(config)) * ``` */ public static async import (config: string): Promise { diff --git a/vcx/wrappers/python3/.gitignore b/vcx/wrappers/python3/.gitignore index e41ffba248..3b334e370d 100644 --- a/vcx/wrappers/python3/.gitignore +++ b/vcx/wrappers/python3/.gitignore @@ -104,3 +104,6 @@ venv.bak/ .mypy_cache/ vcxconfig.json + +*.html +docs/ diff --git a/vcx/wrappers/python3/README.md b/vcx/wrappers/python3/README.md index e69de29bb2..c302f97221 100644 --- a/vcx/wrappers/python3/README.md +++ b/vcx/wrappers/python3/README.md @@ -0,0 +1,11 @@ +## Documentation: +Requires: +* python3 + + Run this commands: +``` +python3 generateDocs.py +``` + +* A directory will be created locally `./docs` which contains subdirectories 'vcx' and within that 'api'. Html files are generated and put here that give details on each api function. + diff --git a/vcx/wrappers/python3/generate_docs.py b/vcx/wrappers/python3/generate_docs.py new file mode 100644 index 0000000000..2bdf378986 --- /dev/null +++ b/vcx/wrappers/python3/generate_docs.py @@ -0,0 +1,42 @@ +import os +import pydoc +import sys + +class DocTree: + def __init__(self, src, dest): + self.basepath = os.getcwd() + sys.path.append(os.path.join(self.basepath, src)) + self.src = src + self.dest = dest + self._make_dest(dest) + self._make_docs(src) + self._move_docs(dest) + + def _make_dest(self, dest): + path = os.path.join(self.basepath, dest) + if os.path.isdir(path): + os.rmdir(path) + os.makedirs(path) + + def _make_docs(self, src): + print('making htmls for ' + src) + pydoc.writedocs(src) + print(os.listdir()) + + def _move_docs(self, dest): + + for f in os.listdir(): + if f.endswith('.html'): + _dest = os.path.join(dest, f) + os.rename(f, _dest) + + +def main(): + dest = 'docs' + src = 'vcx/api' + src = os.path.join(os.getcwd(), src) + ft = DocTree(src, dest) + +if __name__ == '__main__': + main() + diff --git a/vcx/wrappers/python3/vcx/api/connection.py b/vcx/wrappers/python3/vcx/api/connection.py index a8cfdf5e17..e792905ad0 100644 --- a/vcx/wrappers/python3/vcx/api/connection.py +++ b/vcx/wrappers/python3/vcx/api/connection.py @@ -52,11 +52,14 @@ async def create(source_id: str): @staticmethod async def create_with_details(source_id: str, invite_details: str): """ - Create a connection object with an invite, represents a single endpoint and can be used for sending and receiving + Create a connection object with a provided invite, represents a single endpoint and can be used for sending and receiving credentials and proofs + Invite details are provided by the entity offering a connection and generally pulled from a provided QRCode. :param source_id: Institution's unique ID for the connection - :param invite_details: + :param invite_details: A string representing a json object which is provided by an entity that wishes to make a connection. + Example: + connection2 = await Connection.create_with_details('MyBank', invite_details) :return: connection object """ constructor_params = (source_id,) @@ -76,6 +79,9 @@ async def deserialize(data: dict): Create the object from a previously serialized object. :param data: The output of the "serialize" call + Example: + data = await connection1.serialize() + connection2 = await Connection.deserialize(data) :return: A re-instantiated object """ return await Connection._deserialize("vcx_connection_deserialize", @@ -87,6 +93,10 @@ async def connect(self, phone_number: Optional[str]) -> str: Connect securely and privately to the endpoint represented by the object. :param phone_number: optional phone number that will receive SMS with invite details + Example: + phone_number = '8019119191' + connection = await Connection.create('foobar123') + invite_details = await connection.connect(phone_number) :return: the invite details sent via SMS or ready to be sent via some other mechanism (QR for example) """ if not hasattr(Connection.connect, "cb"): @@ -113,7 +123,8 @@ async def _delete(self): async def serialize(self) -> dict: """ Serialize the object for storage - + Example: + data = await connection1.serialize() :return: serialized object """ return await self._serialize(Connection, 'vcx_connection_serialize') @@ -122,7 +133,9 @@ async def update_state(self) -> int: """ Query the agency for the current state of the connection. Used to determine whether the connection has been accepted by both endpoints. - + Example: + connection = await Connection.create(source_id) + assert await connection.update_state() == State.Initialized :return: Current state of the connection """ return await self._update_state(Connection, 'vcx_connection_update_state') @@ -130,7 +143,9 @@ async def update_state(self) -> int: async def get_state(self) -> int: """ Returns the current internal state of the connection. Does NOT query agency for state updates. - + Example: + connection = await Connection.create(source_id) + assert await connection.get_state() == State.Initialized :return: Current internal state of the connection """ return await self._get_state(Connection, 'vcx_connection_get_state') @@ -149,6 +164,9 @@ async def delete(self): NOTE: This eliminates the connection and any ability to use it for any communication. + Example: + connection = await Connection.create(source_id) + await connection.delete() :return: None """ await self._delete() @@ -158,6 +176,11 @@ async def invite_details(self, abbreviated: bool) -> dict: Get the invite details that were sent or can be sent to the endpoint. :param abbreviated: abbreviate invite details or not + Example: + phone_number = '8019119191' + connection = await Connection.create('foobar123') + invite_details = await connection.connect(phone_number) + inivte_details_again = await connection.invite_details() :return: JSON of invite_details sent to connection """ if not hasattr(Connection.invite_details, "cb"): diff --git a/vcx/wrappers/python3/vcx/api/credential_def.py b/vcx/wrappers/python3/vcx/api/credential_def.py index ac54651961..bba6d50f56 100644 --- a/vcx/wrappers/python3/vcx/api/credential_def.py +++ b/vcx/wrappers/python3/vcx/api/credential_def.py @@ -51,6 +51,11 @@ async def create(source_id: str, name: str, schema_id: str, payment_handle: int) :param name: Name of credential definition :param schema_id: The schema ID given during the creation of the schema :param payment_handle: NYI - payment of ledger fee is taken from wallet automatically + Example: + source_id = 'foobar123' + schema_name = 'Schema Name' + payment_handle = 0 + credential_def1 = await CredentialDef.create(source_id, name, schema_id, payment_handle) :return: credential_def object, written to ledger """ constructor_params = (source_id, name, schema_id) @@ -70,12 +75,34 @@ async def create(source_id: str, name: str, schema_id: str, payment_handle: int) constructor_params, c_params) + async def serialize(self) -> dict: + """ + Serialize the object for storage + + :return: serialized object + Example: + source_id = 'foobar123' + schema_name = 'Schema Name' + payment_handle = 0 + credential_def1 = await CredentialDef.create(source_id, name, schema_id, payment_handle) + data1 = await credential_def1.serialize() + :return: A re-instantiated object + """ + return await self._serialize(CredentialDef, 'vcx_credentialdef_serialize') + @staticmethod async def deserialize(data: dict): """ Create the object from a previously serialized object. :param data: The output of the "serialize" call + Example: + source_id = 'foobar123' + schema_name = 'Schema Name' + payment_handle = 0 + credential_def1 = await CredentialDef.create(source_id, name, schema_id, payment_handle) + data1 = await credential_def1.serialize() + credential_def2 = await CredentialDef.deserialize(data1) :return: A re-instantiated object """ try: @@ -88,18 +115,17 @@ async def deserialize(data: dict): except KeyError: raise VcxError(ErrorCode.InvalidCredentialDef, error_message(ErrorCode.InvalidCredentialDef)) - async def serialize(self) -> dict: - """ - Serialize the object for storage - - :return: serialized object - """ - return await self._serialize(CredentialDef, 'vcx_credentialdef_serialize') async def get_cred_def_id(self): """ Get the ledger ID of the object + Example: + source_id = 'foobar123' + schema_name = 'Schema Name' + payment_handle = 0 + credential_def1 = await CredentialDef.create(source_id, name, schema_id, payment_handle) + assert await credential_def.get_cred_def_id() == '2hoqvcwupRTUNkXn6ArYzs:3:CL:2471' :return: ID string """ cb = create_cb(CFUNCTYPE(None, c_uint32, c_uint32, c_char_p)) @@ -110,7 +136,12 @@ async def get_cred_def_id(self): def release(self) -> None: """ destroy the object and release any memory associated with it - + Example: + source_id = 'foobar123' + schema_name = 'Schema Name' + payment_handle = 0 + credential_def1 = await CredentialDef.create(source_id, name, schema_id, payment_handle) + credential_def1.release() :return: None """ self._release(CredentialDef, 'vcx_credentialdef_release') @@ -119,6 +150,12 @@ async def get_payment_txn(self): """ Get the payment transaction information generated when paying the ledger fee + Example: + source_id = 'foobar123' + schema_name = 'Schema Name' + payment_handle = 0 + credential_def1 = await CredentialDef.create(source_id, name, schema_id, payment_handle) + txn = await credential_def1.get_payment_txn() :return: JSON object with input address and output UTXOs """ if not hasattr(CredentialDef.get_payment_txn, "cb"): diff --git a/vcx/wrappers/python3/vcx/api/proof.py b/vcx/wrappers/python3/vcx/api/proof.py index b25fbb85f2..ab4619302a 100644 --- a/vcx/wrappers/python3/vcx/api/proof.py +++ b/vcx/wrappers/python3/vcx/api/proof.py @@ -136,6 +136,7 @@ async def request_proof(self, connection: Connection): async def get_proof(self, connection: Connection) -> list: """ + Example: connection = await Connection.create(source_id) await connection.connect(phone_number) name = "proof name" @@ -143,8 +144,8 @@ async def get_proof(self, connection: Connection) -> list: proof = await Proof.create(source_id, name, requested_attrs) await proof.request_proof(connection) await proof.get_proof(connection) - :param connection: - :return: + :param connection: Handle for the connection to receive a proof from. + :return: List of proofs received from the given connection. """ if not hasattr(Proof.get_proof, "cb"): self.logger.debug("vcx_get_proof: Creating callback") diff --git a/vcx/wrappers/python3/vcx/api/schema.py b/vcx/wrappers/python3/vcx/api/schema.py index be6418d74e..c34aa7561d 100644 --- a/vcx/wrappers/python3/vcx/api/schema.py +++ b/vcx/wrappers/python3/vcx/api/schema.py @@ -71,6 +71,13 @@ async def create(source_id: str, name: str, version: str, attrs: list, payment_h :param version: Version of the schema :param attrs: Atttributes of the schema :param payment_handle: NYI - payment of ledger fee is taken from wallet automatically + Example: + source_id = 'foobar123' + name = 'Address Schema' + version = '1.0' + attrs = ['address', 'city', 'state'] + payment_handle = 0 + schema = await Schema.create(source_id, name, version, attrs, payment_handle) :return: schema object, written to ledger """ constructor_params = (source_id, name, version, attrs) @@ -92,6 +99,14 @@ async def deserialize(data: dict): Create the object from a previously serialized object. :param data: The output of the "serialize" call + Example: + source_id = 'foobar123' + name = 'Address Schema' + version = '1.0' + attrs = ['address', 'city', 'state'] + payment_handle = 0 + schema1 = await Schema.create(source_id, name, version, attrs, payment_handle) + data1 = await schema1.serialize() :return: A re-instantiated object """ try: @@ -115,6 +130,18 @@ async def lookup(source_id: str, schema_id: str): :param source_id: Institution's personal identification for the schema :param schema_id: Ledger schema ID for lookup + Example: + source_id = 'foobar123' + name = 'Address Schema' + version = '1.0' + attrs = ['address', 'city', 'state'] + payment_handle = 0 + schema1 = await Schema.create(source_id, name, version, attrs, payment_handle) + id1 = await schema.get_schema_id() + data = await Schema.lookup(source_id, schema_id) + assert data.attrs.sort() == ['sex', 'age', 'name', 'height'].sort() + assert data.name == 'test-licence' + assert data.handle > 0 :return: schema object """ try: @@ -146,6 +173,14 @@ async def serialize(self) -> dict: """ Serialize the object for storage + Example: + source_id = 'foobar123' + name = 'Address Schema' + version = '1.0' + attrs = ['address', 'city', 'state'] + payment_handle = 0 + schema1 = await Schema.create(source_id, name, version, attrs, payment_handle) + data1 = await schema1.serialize() :return: serialized object """ return await self._serialize(Schema, 'vcx_schema_serialize') @@ -162,6 +197,14 @@ async def get_schema_id(self): """ Get the ledger ID of the object + Example: + source_id = 'foobar123' + name = 'Address Schema' + version = '1.0' + attrs = ['address', 'city', 'state'] + payment_handle = 0 + schema1 = await Schema.create(source_id, name, version, attrs, payment_handle) + id1 = await schema.get_schema_id() :return: ID string """ cb = create_cb(CFUNCTYPE(None, c_uint32, c_uint32, c_char_p)) @@ -173,6 +216,14 @@ async def get_payment_txn(self): """ Get the payment transaction information generated when paying the ledger fee + Example: + source_id = 'foobar123' + name = 'Address Schema' + version = '1.0' + attrs = ['address', 'city', 'state'] + payment_handle = 0 + schema1 = await Schema.create(source_id, name, version, attrs, payment_handle) + txn = await schema1.get_payment_txn() :return: JSON object with input address and output UTXOs """ if not hasattr(Schema.get_payment_txn, "cb"): diff --git a/vcx/wrappers/python3/vcx/api/utils.py b/vcx/wrappers/python3/vcx/api/utils.py index 39812293dd..d2955e0005 100644 --- a/vcx/wrappers/python3/vcx/api/utils.py +++ b/vcx/wrappers/python3/vcx/api/utils.py @@ -4,6 +4,23 @@ async def vcx_agent_provision(config: str) -> None: + """ + Provision an agent in the agency, populate configuration and wallet for this agent. + Example: + import json + enterprise_config = { + 'agency_url': 'https://enym-eagency.pdev.evernym.com', + 'agency_did': 'YRuVCckY6vfZfX9kcQZe3u', + 'agency_verkey': "J8Yct6FwmarXjrE2khZesUXRVVSVczSoa9sFaGe6AD2v", + 'wallet_name': 'LIBVCX_SDK_WALLET', + 'agent_seed': '00000000000000000000000001234561', + 'enterprise_seed': '000000000000000000000000Trustee1', + 'wallet_key': '1234' + } + vcx_config = await vcx_agent_provision(json.dumps(enterprise_config)) + :param config: JSON configuration + :return: Configuration for vcx_init call. + """ logger = logging.getLogger(__name__) if not hasattr(vcx_agent_provision, "cb"): @@ -20,6 +37,11 @@ async def vcx_agent_provision(config: str) -> None: return result.decode() async def vcx_agent_update_info(config: str) -> None: + """ + Update information on the agent (ie, comm method and type) + :param config: + :return: + """ logger = logging.getLogger(__name__) if not hasattr(vcx_agent_update_info, "cb"): @@ -36,6 +58,12 @@ async def vcx_agent_update_info(config: str) -> None: return result async def vcx_ledger_get_fees() -> str: + """ + Get ledger fees from the sovrin network + Example: + fees = await vcx_ledger_get_fees() + :return: JSON representing fees + """ logger = logging.getLogger(__name__) if not hasattr(vcx_ledger_get_fees, "cb"): @@ -49,6 +77,13 @@ async def vcx_ledger_get_fees() -> str: return result async def vcx_messages_download(status: str = None, uids: str = None, pw_dids: str = None) -> str: + """ + Retrieve messages from the specified connection + :param status: + :param uids: + :param pw_dids: + :return: + """ logger = logging.getLogger(__name__) if not hasattr(vcx_messages_download, "cb"): @@ -80,6 +115,11 @@ async def vcx_messages_download(status: str = None, uids: str = None, pw_dids: s return result async def vcx_messages_update_status(msg_json: str): + """ + Update the status of messages from the specified connection + :param msg_json: + :return: + """ logger = logging.getLogger(__name__) if not hasattr(vcx_messages_update_status, "cb"): diff --git a/vcx/wrappers/python3/vcx/api/vcx_init.py b/vcx/wrappers/python3/vcx/api/vcx_init.py index d4c3077d01..802712a81b 100644 --- a/vcx/wrappers/python3/vcx/api/vcx_init.py +++ b/vcx/wrappers/python3/vcx/api/vcx_init.py @@ -4,6 +4,13 @@ async def vcx_init(config_path: str) -> None: + """ + Initializes VCX with config file. + :param config_path: String + Example: + await vcx_init('/home/username/vcxconfig.json') + :return: + """ logger = logging.getLogger(__name__) if not hasattr(vcx_init, "cb"): @@ -21,6 +28,27 @@ async def vcx_init(config_path: str) -> None: async def vcx_init_with_config(config: str) -> None: + """ + + :param config: + Example: + config = { + "agency_did": "L5nbFwXJRmdnJVYhCsy52j", + "agency_verkey": "BQEgx9PJ7JJgt1LadyP45a7JrWdyqkrzrCBGRZ9QVrvL", + "agency_endpoint": "https://cagency.pdev.evernym.com", + "genesis_path":"/var/lib/indy/verity-staging/pool_transactions_genesis", + "institution_name": "institution", + "institution_logo_url": "http://robohash.org/234", + "institution_did": "EwsFhWVoc3Fwqzrwe998aQ", + "institution_verkey": "8brs38hPDkw5yhtzyk2tz7zkp8ijTyWnER165zDQbpK6", + "remote_to_sdk_did": "EtfeMFytvYTKnWwqTScp9D", + "remote_to_sdk_verkey": "8a7hZDyJK1nNCizRCKMr4H4QbDm8Gg2vcbDRab8SVfsi", + "sdk_to_remote_did": "KacwZ2ndG6396KXJ9NDDw6", + "sdk_to_remote_verkey": "B8LgZGxEPcpTJfZkeqXuKNLihM1Awm8yidqsNwYi5QGc" + } + await vcx_init_with_config(config) + :return: + """ logger = logging.getLogger(__name__) if not hasattr(vcx_init_with_config, "cb"): diff --git a/vcx/wrappers/python3/vcx/api/wallet.py b/vcx/wrappers/python3/vcx/api/wallet.py index 3dd52c651b..b16c01ef1d 100644 --- a/vcx/wrappers/python3/vcx/api/wallet.py +++ b/vcx/wrappers/python3/vcx/api/wallet.py @@ -26,6 +26,18 @@ async def close_search(handle: int): @staticmethod async def open_search(type_: str, query: dict, options: dict): + """ + Opens a search handle within the storage wallet. + + :param type_: String + :param query: dictionary + :param options: dictionary + Example: + query_json = {"tagName1": "str1"} + type_ = 'TestType' + search_handle = await Wallet.open_search(type_, query_json, None) + :return: int + """ logger = logging.getLogger(__name__) if not hasattr(Wallet.open_search, "cb"): @@ -47,6 +59,18 @@ async def open_search(type_: str, query: dict, options: dict): @staticmethod async def search_next_records(handle: int, count: int): + """ + Searches for next n record from an open search handle + + :param handle: int + :param count: int + Example: + query_json = {"tagName1": "str1"} + type_ = 'TestType' + search_handle = await Wallet.open_search(type_, query_json, None) + results = await Wallet.search_next_records(search_handle, 5) + :return: + """ logger = logging.getLogger(__name__) if not hasattr(Wallet.search_next_records, "cb"): @@ -65,6 +89,28 @@ async def search_next_records(handle: int, count: int): @staticmethod async def get_record(type_: str, id: str, options: str): + """ + Retrieves a record from the wallet storage. + :param type_: String + :param id: String + :param options: String + Example: + import json + await Wallet.add_record({ + 'id': 'RecordId', + 'tags': json.dumps({ + 'tag1': 'unencrypted value1', + '~encryptedTag', 'this value is encrypted, + 'integerTag', 1 + }), + 'type_': 'TestType', + 'value': 'RecordValue' + }) + options = json.dumps({"retrieveType": True, "retrieveValue": True, "retrieveTags": True}) + record = await Wallet.get_record('TestType', 'RecordId', options) + :return: + :return: + """ logger = logging.getLogger(__name__) if not hasattr(Wallet.get_record, "cb"): @@ -85,6 +131,25 @@ async def get_record(type_: str, id: str, options: str): @staticmethod async def delete_record(type_: str, id: str): + """ + Delete a record from the storage wallet. + + :param type_: + :param id: + Example: + await Wallet.add_record({ + 'id': 'RecordId', + 'tags': json.dumps({ + 'tag1': 'unencrypted value1', + '~encryptedTag', 'this value is encrypted, + 'integerTag', 1 + }), + 'type_': 'TestType', + 'value': 'RecordValue' + }) + await Wallet.delete_record('TestType', 'RecordId') + :return: + """ logger = logging.getLogger(__name__) if not hasattr(Wallet.delete_record, "cb"): @@ -103,6 +168,26 @@ async def delete_record(type_: str, id: str): @staticmethod async def delete_record_tags(type_: str, id: str, tags: list ): + """ + Delete tags associated with a record + :param type_: + :param id: + :param tags: + + Example: + await Wallet.add_record({ + 'id': 'RecordId', + 'tags': json.dumps({ + 'tag1': 'unencrypted value1', + '~encryptedTag', 'this value is encrypted, + 'integerTag', 1 + }), + 'type_': 'TestType', + 'value': 'RecordValue' + }) + await Wallet.delete_record_tags('TestType', 'RecordId', ['tag1', 'integerTag']) + :return: + """ logger = logging.getLogger(__name__) if not hasattr(Wallet.delete_record_tags, "cb"): @@ -124,6 +209,21 @@ async def delete_record_tags(type_: str, id: str, tags: list ): @staticmethod async def add_record_tags(type_: str, id: str, tags: str): + """ + Adds tags to a record already stored in the storage wallet. + :param type_: String + :param id: String + :param tags: String + Example: + import json + await Wallet.add_record({ + 'id': 'RecordId', + 'tags': '{}', + 'type_': 'TestType', + 'value': 'RecordValue + await Wallet.add_record_tags('TestType', 'RecordId', json.dumps({'addthistag':'valuetag1'})) + :return: + """ logger = logging.getLogger(__name__) if not hasattr(Wallet.add_record_tags, "cb"): @@ -144,6 +244,21 @@ async def add_record_tags(type_: str, id: str, tags: str): @staticmethod async def update_record_tags(type_: str, id: str, tags: str): + """ + Updates the tags on a record, removing any previous value. + :param type_: String + :param id: String + :param tags: String + Example: + import json + await Wallet.add_record({ + 'id': 'RecordId', + 'tags': json.dumps({'foobar':'this value will get overwritten'}), + 'type_': 'TestType', + 'value': 'RecordValue + await Wallet.update_record_tags('TestType', 'RecordId', json.dumps({'foobar':'new value'})) + :return: + """ logger = logging.getLogger(__name__) if not hasattr(Wallet.update_record_tags, "cb"): @@ -164,6 +279,20 @@ async def update_record_tags(type_: str, id: str, tags: str): @staticmethod async def update_record_value(type_: str, id: str, value: str): + """ + Updates the value of a record + :param type_: String + :param id: String + :param value: String + Example: + await Wallet.add_record({ + 'id': 'RecordId', + 'tags': '{}', + 'type_': 'TestType', + 'value': 'this will be overwritten' }) + await Wallet.update_record('TestType', 'RecordId', 'new value') + :return: + """ logger = logging.getLogger(__name__) if not hasattr(Wallet.update_record_value, "cb"): @@ -184,6 +313,26 @@ async def update_record_value(type_: str, id: str, value: str): @staticmethod async def add_record(type_: str, id: str, value: str, tags: str): + """ + + :param type_: String + :param id: String + :param value: String + :param tags: Dictionary + Example: + import json + await Wallet.add_record({ + 'id': 'RecordId', + 'tags': json.dumps({ + 'tag1': 'unencrypted value1', + '~encryptedTag', 'this value is encrypted, + 'integerTag', 1 + }), + 'type_': 'TestType', + 'value': 'RecordValue' + }) + :return: + """ logger = logging.getLogger(__name__) if not hasattr(Wallet.add_record, "cb"): @@ -206,6 +355,14 @@ async def add_record(type_: str, id: str, value: str, tags: str): @staticmethod async def get_token_info(handle: int) -> str: + """ + Retrieves from the ledger token info associated with the wallet. + :param handle: + Example: + payment_handle = 0 // payment handle is always 0, for now. + info = await Wallet.get_token_info(payment_handle) + :return: + """ logger = logging.getLogger(__name__) if not hasattr(Wallet.get_token_info, "cb"): @@ -223,6 +380,13 @@ async def get_token_info(handle: int) -> str: @staticmethod async def create_payment_address(seed: str = None) -> str: + """ + Creates a payment address inside the wallet. + :param seed: String + Example: + address = await Wallet.create_payment_address('00000000000000000000000001234567') + :return: String + """ logger = logging.getLogger(__name__) if not hasattr(Wallet.create_payment_address, "cb"): @@ -243,6 +407,15 @@ async def create_payment_address(seed: str = None) -> str: @staticmethod async def validate_payment_address(address: str) -> None: + """ + Determines whether a payment address is valid or not + :param address: String + Example: + address = await Wallet.create_payment_address('00000000000000000000000001234567') + b = await Wallet.validate_payment_address(address) + :return: Boolean + """ + logger = logging.getLogger(__name__) if not hasattr(Wallet.validate_payment_address, "cb"): @@ -259,6 +432,19 @@ async def validate_payment_address(address: str) -> None: @staticmethod async def send_tokens(payment_handle: int, tokens: int, address: str) -> str: + """ + Sends tokens to an address + payment_handle is always 0 + :param payment_handle: Integer + :param tokens: Integer + :param address: String + Example: + payment_handle = 0 + amount = 1000 + address = await Wallet.create_payment_address('00000000000000000000000001234567') + await Wallet.send_tokens(payment_handle, amount, address) + :return: + """ logger = logging.getLogger(__name__) if not hasattr(Wallet.send_tokens, "cb"):