# panda3d.core.DocumentSpec¶

from panda3d.core import DocumentSpec

class DocumentSpec

A descriptor that refers to a particular version of a document. This includes the URL of the document and its identity tag and last-modified dates.

The DocumentSpec may also be used to request a newer document than a particular one if available, for instance to refresh a cached document.

Inheritance diagram

__init__() → None
__init__(copy: DocumentSpec) → None
__init__(url: URLSpec) → None
__init__(url: str) → None
assign(copy: DocumentSpec) → DocumentSpec
Return type

DocumentSpec

compareTo(other: DocumentSpec) → int
setUrl(url: URLSpec) → None

Changes the URL of the DocumentSpec without modifying its other properties. Normally this would be a strange thing to do, because the tag and date are usually strongly associated with the URL. To get a DocumentSpec pointing to a new URL, you would normally create a new DocumentSpec object.

getUrl() → URLSpec

Retrieves the URL of the DocumentSpec.

Return type

URLSpec

setTag(tag: HTTPEntityTag) → None

Changes the identity tag associated with the DocumentSpec.

hasTag() → bool

Returns true if an identity tag is associated with the DocumentSpec.

getTag() → HTTPEntityTag

Returns the identity tag associated with the DocumentSpec, if there is one. It is an error to call this if hasTag() returns false.

The identity tag is set by the HTTP server to uniquely refer to a particular version of a document.

Return type

HTTPEntityTag

clearTag() → None

Removes the identity tag associated with the DocumentSpec, if there is one.

setDate(date: HTTPDate) → None

Changes the last-modified date associated with the DocumentSpec.

hasDate() → bool

Returns true if a last-modified date is associated with the DocumentSpec.

getDate() → HTTPDate

Returns the last-modified date associated with the DocumentSpec, if there is one. It is an error to call this if hasDate() returns false.

Return type

HTTPDate

clearDate() → None

Removes the last-modified date associated with the DocumentSpec, if there is one.

setRequestMode(request_mode: RequestMode) → None

Sets the request mode of this DocumentSpec. This is only relevant when using the DocumentSpec to generate a request (for instance, in HTTPChannel). This specifies whether the document request will ask the server for a newer version than the indicated version, or the exact version, neither, or either.

The possible values are:

RM_any: ignore date and tag (if specified), and retrieve any document that matches the URL. For a subrange request, if the document matches the version indicated exactly, retrieve the subrange only; otherwise, retrieve the entire document.

RM_equal: request only the precise version of the document that matches the particular date and/or tag exactly, if specified; fail if this version is not available.

RM_newer: request any document that is newer than the version indicated by the particular date and/or tag; fail if only that version (or older versions) are available.

RM_newer_or_equal: request any document that matches the version indicated by the particular date and/or tag, or is a newer version; fail if only older versions are available.

In any of the above, you may specify either or both of the last-modified date and the identity tag, whichever is known to the client.

The default mode is RM_any.

getRequestMode() → RequestMode

Returns the request mode of this DocumentSpec. See setRequestMode().

Return type

RequestMode

setCacheControl(cache_control: CacheControl) → None

Specifies what kind of cached value is acceptable for this document. Warning: some HTTP proxies may not respect this setting and may return a cached result anyway.

CC_allow_cache: the normal HTTP behavior; the server may return a cached value if it believes it is valid.

CC_revalidate: a proxy is forced to contact the origin server and verify that is cached value is in fact still valid before it returns it.

CC_no_cache: a proxy must not return its cached value at all, but is forced to go all the way back to the origin server for the official document.

The default mode is CC_allow_cache.

getCacheControl() → CacheControl

Returns the request mode of this DocumentSpec. See setCacheControl().

Return type

CacheControl

input(in: istream) → bool

Can be used to read in the DocumentSpec from a stream generated either by output() or write(). Returns true on success, false on failure.

output(out: ostream) → None
write(out: ostream, indent_level: int) → None
property url
Getter

Retrieves the URL of the DocumentSpec.

Setter

Changes the URL of the DocumentSpec without modifying its other properties. Normally this would be a strange thing to do, because the tag and date are usually strongly associated with the URL. To get a DocumentSpec pointing to a new URL, you would normally create a new DocumentSpec object.

Return type

URLSpec

property tag
Getter

Returns the identity tag associated with the DocumentSpec, if there is one. It is an error to call this if hasTag() returns false.

The identity tag is set by the HTTP server to uniquely refer to a particular version of a document.

Setter

Changes the identity tag associated with the DocumentSpec.

Return type

HTTPEntityTag

property date
Getter

Returns the last-modified date associated with the DocumentSpec, if there is one. It is an error to call this if hasDate() returns false.

Setter

Changes the last-modified date associated with the DocumentSpec.

Return type

HTTPDate

property request_mode
Getter

Returns the request mode of this DocumentSpec. See setRequestMode().

Setter

Sets the request mode of this DocumentSpec. This is only relevant when using the DocumentSpec to generate a request (for instance, in HTTPChannel). This specifies whether the document request will ask the server for a newer version than the indicated version, or the exact version, neither, or either.

The possible values are:

RM_any: ignore date and tag (if specified), and retrieve any document that matches the URL. For a subrange request, if the document matches the version indicated exactly, retrieve the subrange only; otherwise, retrieve the entire document.

RM_equal: request only the precise version of the document that matches the particular date and/or tag exactly, if specified; fail if this version is not available.

RM_newer: request any document that is newer than the version indicated by the particular date and/or tag; fail if only that version (or older versions) are available.

RM_newer_or_equal: request any document that matches the version indicated by the particular date and/or tag, or is a newer version; fail if only older versions are available.

In any of the above, you may specify either or both of the last-modified date and the identity tag, whichever is known to the client.

The default mode is RM_any.

Return type

RequestMode

property cache_control
Getter

Returns the request mode of this DocumentSpec. See setCacheControl().

Setter

Specifies what kind of cached value is acceptable for this document. Warning: some HTTP proxies may not respect this setting and may return a cached result anyway.

CC_allow_cache: the normal HTTP behavior; the server may return a cached value if it believes it is valid.

CC_revalidate: a proxy is forced to contact the origin server and verify that is cached value is in fact still valid before it returns it.

CC_no_cache: a proxy must not return its cached value at all, but is forced to go all the way back to the origin server for the official document.

The default mode is CC_allow_cache.

Return type

CacheControl

enum RequestMode
enumerator RM_any = 0
enumerator RM_equal = 1
enumerator RM_newer = 2
enumerator RM_equal_or_newer = 3
enum CacheControl
enumerator CC_allow_cache = 0
enumerator CC_revalidate = 1
enumerator CC_no_cache = 2