bpo-28157: Improvements for the time module documentation (GH-928) · python/cpython@703ff38 (original) (raw)

`@@ -118,14 +118,10 @@ An explanation of some terminology and conventions is in order.

118

`+-------------------------+-------------------------+-------------------------+

119

120

121

The module defines the following functions and data items:

122

-

123

.. data:: altzone

124

-

125

The offset of the local DST timezone, in seconds west of UTC, if one is defined.

126

This is negative if the local DST timezone is east of UTC (as in Western Europe,

127


 including the UK). Only use this if ``daylight`` is nonzero.

121

.. _time-functions:

128

122

123

Functions

124

129

125

130

126

`.. function:: asctime([t])

131

127

`@@ -181,7 +177,8 @@ The module defines the following functions and data items:

181

177

182

178

`.. function:: clock_getres(clk_id)

183

179

184

Return the resolution (precision) of the specified clock clk_id.

180

Return the resolution (precision) of the specified clock clk_id. Refer to

181

`` +

:ref:time-clock-id-constants for a list of accepted values for clk_id.

185

182

186

183

` Availability: Unix.

187

184

`@@ -190,7 +187,8 @@ The module defines the following functions and data items:

190

187

191

188

`.. function:: clock_gettime(clk_id)

192

189

193

Return the time of the specified clock clk_id.

190

Return the time of the specified clock clk_id. Refer to

191

`` +

:ref:time-clock-id-constants for a list of accepted values for clk_id.

194

192

195

193

` Availability: Unix.

196

194

`@@ -199,66 +197,8 @@ The module defines the following functions and data items:

199

197

200

198

`.. function:: clock_settime(clk_id, time)

201

199

202

Set the time of the specified clock clk_id.

203

-

204

Availability: Unix.

205

-

206

.. versionadded:: 3.3

207

-

208

-

209

.. data:: CLOCK_HIGHRES

210

-

211

The Solaris OS has a CLOCK_HIGHRES timer that attempts to use an optimal

212

hardware source, and may give close to nanosecond resolution. CLOCK_HIGHRES

213

is the nonadjustable, high-resolution clock.

214

-

215

Availability: Solaris.

216

-

217

.. versionadded:: 3.3

218

-

219

-

220

.. data:: CLOCK_MONOTONIC

221

-

222

Clock that cannot be set and represents monotonic time since some unspecified

223

starting point.

224

-

225

Availability: Unix.

226

-

227

.. versionadded:: 3.3

228

-

229

-

230

.. data:: CLOCK_MONOTONIC_RAW

231

-

232

`` -

Similar to :data:CLOCK_MONOTONIC, but provides access to a raw

233

hardware-based time that is not subject to NTP adjustments.

234

-

235

Availability: Linux 2.6.28 or later.

236

-

237

.. versionadded:: 3.3

238

-

239

-

240

.. data:: CLOCK_PROCESS_CPUTIME_ID

241

-

242

High-resolution per-process timer from the CPU.

243

-

244

Availability: Unix.

245

-

246

.. versionadded:: 3.3

247

-

248

-

249

.. data:: CLOCK_REALTIME

250

-

251

System-wide real-time clock. Setting this clock requires appropriate

252

privileges.

253

-

254

Availability: Unix.

255

-

256

.. versionadded:: 3.3

257

-

258

-

259

.. data:: CLOCK_THREAD_CPUTIME_ID

260

-

261

Thread-specific CPU-time clock.

200

Set the time of the specified clock clk_id. Currently,

201

`` +

:data:CLOCK_REALTIME is the only accepted value for clk_id.

262

202

263

203

` Availability: Unix.

264

204

`@@ -273,11 +213,6 @@ The module defines the following functions and data items:

273

213

``` asctime(localtime(secs)). Locale information is not used by :func:ctime.


`274`

`214`

``

`275`

`215`

``

`276`

``

`-

.. data:: daylight

`

`277`

``

`-`

`278`

``

`-

Nonzero if a DST timezone is defined.

`

`279`

``

`-`

`280`

``

`-`

`281`

`216`

`.. function:: get_clock_info(name)

`

`282`

`217`

``

`283`

`218`

` Get information on the specified clock as a namespace object.

`

`@@ -295,7 +230,7 @@ The module defines the following functions and data items:

`

`295`

`230`

```  - *adjustable*: ``True`` if the clock can be changed automatically (e.g. by

296

231

``` a NTP daemon) or manually by the system administrator, False otherwise


`297`

`232`

` - *implementation*: The name of the underlying C function used to get

`

`298`

``

`-

the clock value

`

``

`233`

`` +

the clock value. Refer to :ref:`time-clock-id-constants` for possible values.

``

`299`

`234`

```  - *monotonic*: ``True`` if the clock cannot go backward,

300

235

``` False otherwise


`301`

`236`

``  - *resolution*: The resolution of the clock in seconds (:class:`float`)

``

`@@ -623,18 +558,6 @@ The module defines the following functions and data items:

`

`623`

`558`

`` :class:`struct_time` object is returned, from which the components

``

`624`

`559`

` of the calendar date may be accessed as attributes.

`

`625`

`560`

``

`626`

``

`-

.. data:: timezone

`

`627`

``

`-`

`628`

``

`-

The offset of the local (non-DST) timezone, in seconds west of UTC (negative in

`

`629`

``

`-

most of Western Europe, positive in the US, zero in the UK).

`

`630`

``

`-`

`631`

``

`-`

`632`

``

`-

.. data:: tzname

`

`633`

``

`-`

`634`

``

`-

A tuple of two strings: the first is the name of the local non-DST timezone, the

`

`635`

``

`-

second is the name of the local DST timezone. If no DST timezone is defined,

`

`636`

``

`-

the second string should not be used.

`

`637`

``

`-`

`638`

`561`

``

`639`

`562`

`.. function:: tzset()

`

`640`

`563`

``

`@@ -724,6 +647,111 @@ The module defines the following functions and data items:

`

`724`

`647`

` ('EET', 'EEST')

`

`725`

`648`

``

`726`

`649`

``

``

`650`

`+

.. _time-clock-id-constants:

`

``

`651`

`+`

``

`652`

`+

Clock ID Constants

`

``

`653`

`+

------------------

`

``

`654`

`+`

``

`655`

`` +

These constants are used as parameters for :func:`clock_getres` and

``

``

`656`

`` +

:func:`clock_gettime`.

``

``

`657`

`+`

``

`658`

`+

.. data:: CLOCK_HIGHRES

`

``

`659`

`+`

``

`660`

``` +

The Solaris OS has a ``CLOCK_HIGHRES`` timer that attempts to use an optimal

661

hardware source, and may give close to nanosecond resolution.

662


 ``CLOCK_HIGHRES`` is the nonadjustable, high-resolution clock.

663

+

664

Availability: Solaris.

665

+

666

.. versionadded:: 3.3

667

+

668

+

669

.. data:: CLOCK_MONOTONIC

670

+

671

Clock that cannot be set and represents monotonic time since some unspecified

672

starting point.

673

+

674

Availability: Unix.

675

+

676

.. versionadded:: 3.3

677

+

678

+

679

.. data:: CLOCK_MONOTONIC_RAW

680

+

681

`` +

Similar to :data:CLOCK_MONOTONIC, but provides access to a raw

682

hardware-based time that is not subject to NTP adjustments.

683

+

684

Availability: Linux 2.6.28 or later.

685

+

686

.. versionadded:: 3.3

687

+

688

+

689

.. data:: CLOCK_PROCESS_CPUTIME_ID

690

+

691

High-resolution per-process timer from the CPU.

692

+

693

Availability: Unix.

694

+

695

.. versionadded:: 3.3

696

+

697

+

698

.. data:: CLOCK_THREAD_CPUTIME_ID

699

+

700

Thread-specific CPU-time clock.

701

+

702

Availability: Unix.

703

+

704

.. versionadded:: 3.3

705

+

706

+

707

The following constant is the only parameter that can be sent to

708

`` +

:func:clock_settime.

709

+

710

.. data:: CLOCK_REALTIME

711

+

712

System-wide real-time clock. Setting this clock requires appropriate

713

privileges.

714

+

715

Availability: Unix.

716

+

717

.. versionadded:: 3.3

718

+

719

+

720

.. _time-timezone-constants:

721

+

722

Timezone Constants

723

724

+

725

.. data:: altzone

726

+

727

The offset of the local DST timezone, in seconds west of UTC, if one is defined.

728

This is negative if the local DST timezone is east of UTC (as in Western Europe,

729


 including the UK). Only use this if ``daylight`` is nonzero. See note below.

730

+

731

.. data:: daylight

732

+

733

Nonzero if a DST timezone is defined. See note below.

734

+

735

.. data:: timezone

736

+

737

The offset of the local (non-DST) timezone, in seconds west of UTC (negative in

738

most of Western Europe, positive in the US, zero in the UK). See note below.

739

+

740

.. data:: tzname

741

+

742

A tuple of two strings: the first is the name of the local non-DST timezone, the

743

second is the name of the local DST timezone. If no DST timezone is defined,

744

the second string should not be used. See note below.

745

+

746

.. note::

747

+

748

`` +

For the above Timezone constants (:data:altzone, :data:daylight, :data:timezone,

749

`` +

and :data:tzname), the value is determined by the timezone rules in effect

750

`` +

at module load time or the last time :func:tzset is called and may be incorrect

751

`` +

for times in the past. It is recommended to use the :attr:tm_gmtoff and

752

`` +

:attr:tm_zone results from :func:localtime to obtain timezone information.

753

+

754

+

727

755

`.. seealso::

728

756

729

757

`` Module :mod:datetime