1
2.. _document_api:
3
4Document objects
5================
6
7The main Document and related objects.
8
9
10|Document| constructor
11----------------------
12
13.. autofunction:: docx.Document
14
15
16|Document| objects
17------------------
18
19.. autoclass:: docx.document.Document()
20   :members:
21   :exclude-members: styles_part
22
23
24|CoreProperties| objects
25-------------------------
26
27Each |Document| object provides access to its |CoreProperties| object via its
28:attr:`core_properties` attribute. A |CoreProperties| object provides
29read/write access to the so-called *core properties* for the document. The
30core properties are author, category, comments, content_status, created,
31identifier, keywords, language, last_modified_by, last_printed, modified,
32revision, subject, title, and version.
33
34Each property is one of three types, |str|, |datetime|, or |int|. String
35properties are limited in length to 255 characters and return an empty string
36('') if not set. Date properties are assigned and returned as |datetime|
37objects without timezone, i.e. in UTC. Any timezone conversions are the
38responsibility of the client. Date properties return |None| if not set.
39
40|docx| does not automatically set any of the document core properties other
41than to add a core properties part to a presentation that doesn't have one
42(very uncommon). If |docx| adds a core properties part, it contains default
43values for the title, last_modified_by, revision, and modified properties.
44Client code should update properties like revision and last_modified_by
45if that behavior is desired.
46
47.. currentmodule:: docx.opc.coreprops
48
49.. class:: CoreProperties
50
51   .. attribute:: author
52
53      *string* -- An entity primarily responsible for making the content of the
54      resource.
55
56   .. attribute:: category
57
58      *string* -- A categorization of the content of this package. Example
59      values might include: Resume, Letter, Financial Forecast, Proposal,
60      or Technical Presentation.
61
62   .. attribute:: comments
63
64      *string* -- An account of the content of the resource.
65
66   .. attribute:: content_status
67
68      *string* -- completion status of the document, e.g. 'draft'
69
70   .. attribute:: created
71
72      *datetime* -- time of intial creation of the document
73
74   .. attribute:: identifier
75
76      *string* -- An unambiguous reference to the resource within a given
77      context, e.g. ISBN.
78
79   .. attribute:: keywords
80
81      *string* -- descriptive words or short phrases likely to be used as
82      search terms for this document
83
84   .. attribute:: language
85
86      *string* -- language the document is written in
87
88   .. attribute:: last_modified_by
89
90      *string* -- name or other identifier (such as email address) of person
91      who last modified the document
92
93   .. attribute:: last_printed
94
95      *datetime* -- time the document was last printed
96
97   .. attribute:: modified
98
99      *datetime* -- time the document was last modified
100
101   .. attribute:: revision
102
103      *int* -- number of this revision, incremented by Word each time the
104      document is saved. Note however |docx| does not automatically increment
105      the revision number when it saves a document.
106
107   .. attribute:: subject
108
109      *string* -- The topic of the content of the resource.
110
111   .. attribute:: title
112
113      *string* -- The name given to the resource.
114
115   .. attribute:: version
116
117      *string* -- free-form version string
118