From 0ab3ced9222c8e1d1dc386914181f4a6e3b4a01b Mon Sep 17 00:00:00 2001 From: Daniel Krook Date: Wed, 9 Mar 2016 14:56:39 -0500 Subject: [PATCH] Updated the wording in the database architecture docs. Change-Id: Ie4f6a7076f8a06970fbe846b9aaa0e544f528aa5 --- doc/source/database_architecture.rst | 135 +++++++++++++-------------- 1 file changed, 67 insertions(+), 68 deletions(-) diff --git a/doc/source/database_architecture.rst b/doc/source/database_architecture.rst index 8b96f73a..6e88a1a4 100644 --- a/doc/source/database_architecture.rst +++ b/doc/source/database_architecture.rst @@ -21,18 +21,18 @@ Glance database architecture Glance Database Public API ~~~~~~~~~~~~~~~~~~~~~~~~~~ -Glance DB API contains several methods to process information from -and to a persistent storage. Below you can find a list of public -methods grouped by categories. +The Glance Database API contains several methods for moving image metadata to +and from persistent storage. You can find a list of public methods grouped by +category below. Common parameters for image methods ----------------------------------- -The following parameters can be applied to all the below image methods: - - ``context`` corresponds to a value with glance.context.RequestContext +The following parameters can be applied to all of the image methods below: + - ``context`` — corresponds to a glance.context.RequestContext object, which stores the information on how a user accesses - the system, as well as additional request information; - - ``image_id`` — a string corresponding to the image identifier; + the system, as well as additional request information. + - ``image_id`` — a string corresponding to the image identifier. - ``memb_id`` — a string corresponding to the member identifier of the image. @@ -41,73 +41,72 @@ Image basic methods **Image processing methods:** -#. ``image_create(context, values)`` - creates a new image record +#. ``image_create(context, values)`` — creates a new image record with parameters listed in the *values* dictionary. Returns a - dictionary representation of a newly created *glance.db.sqlalchemy. - models.Image* object. + dictionary representation of a newly created + *glance.db.sqlalchemy.models.Image* object. #. ``image_update(context, image_id, values, purge_props=False, - from_state=None)`` - updates the existing image with an identifier - *image_id* with values listed in the *values* dictionary. Returns a + from_state=None)`` — updates the existing image with the identifier + *image_id* with the values listed in the *values* dictionary. Returns a dictionary representation of a newly created *Image* object. Optional parameters are: - - ``purge_props`` - a flag indicating that all the existing - properties not listed in the *values[‘properties’]* should be + - ``purge_props`` — a flag indicating that all the existing + properties not listed in the *values['properties']* should be deleted; - - ``from_state`` - a string filter indicating that the updated + - ``from_state`` — a string filter indicating that the updated image must be in the specified state. -#. ``image_destroy(context, image_id)`` - deletes all the database - record of an image with an identifier *image_id*, like tags, - properties, and members, and sets a ‘deleted’ status to all the +#. ``image_destroy(context, image_id)`` — deletes all the database + record of an image with the identifier *image_id* (like tags, + properties, and members) and sets a 'deleted' status on all the image locations. -#. ``image_get(context, image_id, force_show_deleted=False)`` - - gets an image with an identifier *image_id* and returns its - dictionary representation. A parameter *force_show_deleted* is +#. ``image_get(context, image_id, force_show_deleted=False)`` — + gets an image with the identifier *image_id* and returns its + dictionary representation. The parameter *force_show_deleted* is a flag that indicates to show image info even if it was - ‘deleted’, or its ‘pending_delete’ statuses. + 'deleted', or its 'pending_delete' statuses. #. ``image_get_all(context, filters=None, marker=None, limit=None, sort_key=None, sort_dir=None, member_status='accepted', - is_public=None, admin_as_user=False, return_tag=False)`` - gets + is_public=None, admin_as_user=False, return_tag=False)`` — gets all the images that match zero or more filters. Optional parameters are: - - ``filters`` - dict of filter keys and values. If a 'properties' - key is present, it is treated as a dict of key/value filters in + - ``filters`` — dictionary of filter keys and values. If a 'properties' + key is present, it is treated as a dictionary of key/value filters in the attribute of the image properties. - - ``marker`` - image id after which a page should start; - - ``limit`` - maximum number of images to return; - - ``sort_key`` - list of image attributes by which results should - be sorted; - - ``sort_dir`` - directions in which results should be sorted - (asc, desc); - - ``member_status`` - only returns shared images that have this - membership status; - - ``is_public`` - if true, returns only public images. If false, + - ``marker`` — image id after which a page should start. + - ``limit`` — maximum number of images to return. + - ``sort_key`` — list of image attributes by which results should + be sorted. + - ``sort_dir`` — direction in which results should be sorted + (asc, desc). + - ``member_status`` — only returns shared images that have this + membership status. + - ``is_public`` — if true, returns only public images. If false, returns only private and shared images. - - ``admin_as_user`` - for backwards compatibility. If true, admin - receives an equivalent set of images that he would see if he was - a regular user. - - ``return_tag`` - indicates whether an image entry in the result + - ``admin_as_user`` — for backwards compatibility. If true, an admin + sees the same set of images that would be seen by a regular user. + - ``return_tag`` — indicates whether an image entry in the result includes its relevant tag entries. This can improve upper-layer - query performance and prevent using separated calls. + query performance and avoid using separate calls. Image location methods ---------------------- **Image location processing methods:** -#. ``image_location_add(context, image_id, location)`` - - adds a new location to an image with an identifier image_id. This +#. ``image_location_add(context, image_id, location)`` — + adds a new location to an image with the identifier *image_id*. This location contains values listed in the dictionary *location*. -#. ``image_location_update(context, image_id, location)`` - updates - an existing location with an identifier *location[‘id’]* - for an image with an identifier *image_id* with values listed in +#. ``image_location_update(context, image_id, location)`` — updates + an existing location with the identifier *location['id']* + for an image with the identifier *image_id* with values listed in the dictionary *location*. #. ``image_location_delete(context, image_id, location_id, status, - delete_time=None)`` - sets a 'deleted' or 'pending_delete' - *status* to an existing location record with an identifier - *location_id* for an image with an identifier *image_id*. + delete_time=None)`` — sets a 'deleted' or 'pending_delete' + *status* to an existing location record with the identifier + *location_id* for an image with the identifier *image_id*. Image property methods ---------------------- @@ -118,34 +117,34 @@ Image property methods **Image property processing methods:** -#. ``image_property_create(context, values)`` - creates +#. ``image_property_create(context, values)`` — creates a property record with parameters listed in the *values* dictionary - for an image with *values[‘id’]*. Returns a dictionary representation + for an image with *values['id']*. Returns a dictionary representation of a newly created *ImageProperty* object. -#. ``image_property_delete(context, prop_ref, image_ref)`` - deletes an +#. ``image_property_delete(context, prop_ref, image_ref)`` — deletes an existing property record with a name *prop_ref* for an image with - an identifier *image_ref*. + the identifier *image_ref*. Image member methods -------------------- **Methods to handle image memberships:** -#. ``image_member_create(context, values)`` - creates a member record +#. ``image_member_create(context, values)`` — creates a member record with properties listed in the *values* dictionary for an image - with *values[‘id’]*. Returns a dictionary representation + with *values['id']*. Returns a dictionary representation of a newly created *ImageMember* object. -#. ``image_member_update(context, memb_id, values)`` - updates an +#. ``image_member_update(context, memb_id, values)`` — updates an existing member record with properties listed in the *values* - dictionary for an image with *values[‘id’]*. Returns a dictionary + dictionary for an image with *values['id']*. Returns a dictionary representation of an updated member record. -#. ``image_member_delete(context, memb_id)`` - deletes an existing +#. ``image_member_delete(context, memb_id)`` — deletes an existing member record with *memb_id*. #. ``image_member_find(context, image_id=None, member=None, status=None)`` - - returns all members for a given context with optional image + — returns all members for a given context with optional image identifier (*image_id*), member name (*member*), and member status (*status*) parameters. -#. ``image_member_count(context, image_id)`` - returns a number of image +#. ``image_member_count(context, image_id)`` — returns a number of image members for an image with *image_id*. Image tag methods @@ -153,30 +152,30 @@ Image tag methods **Methods to process images tags:** -#. ``image_tag_set_all(context, image_id, tags)`` - changes all the +#. ``image_tag_set_all(context, image_id, tags)`` — changes all the existing tags for an image with *image_id* to the tags listed in the *tags* param. To remove all tags, a user just should provide an empty list. -#. ``image_tag_create(context, image_id, value)`` - adds a *value* +#. ``image_tag_create(context, image_id, value)`` — adds a *value* to tags for an image with *image_id*. Returns the value of a newly created tag. -#. ``image_tag_delete(context, image_id, value)`` - removes a *value* +#. ``image_tag_delete(context, image_id, value)`` — removes a *value* from tags for an image with *image_id*. -#. ``image_tag_get_all(context, image_id)`` - returns a list of tags +#. ``image_tag_get_all(context, image_id)`` — returns a list of tags for a specific image. Image info methods ------------------ -The next two methods inform a user about his ability to modify -and view an image. *image* param here is a dictionary representation +The next two methods inform a user about his or her ability to modify +and view an image. The *image* parameter here is a dictionary representation of an *Image* object. -#. ``is_image_mutable(context, image)`` - informs a user - about the possibility to modify an image with a given context. +#. ``is_image_mutable(context, image)`` — informs a user + about the possibility to modify an image with the given context. Returns True if the image is mutable in this context. -#. ``is_image_visible(context, image, status=None)`` - informs about - the possibility to observe the image details with a given context +#. ``is_image_visible(context, image, status=None)`` — informs about + the possibility to see the image details with the given context and optionally with a status. Returns True if the image is visible in this context.