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