[3.6] bpo-28157: Improvements for the time module documentation (GH-928) · python/cpython@764969a (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

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

165

161

166

162

`.. function:: clock_getres(clk_id)

167

163

168

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

164

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

165

`` +

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

169

166

170

167

` Availability: Unix.

171

168

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

174

171

175

172

`.. function:: clock_gettime(clk_id)

176

173

177

Return the time of the specified clock clk_id.

174

Return the time of the specified clock clk_id. Refer to

175

`` +

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

178

176

179

177

` Availability: Unix.

180

178

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

183

181

184

182

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

185

183

186

Set the time of the specified clock clk_id.

187

-

188

Availability: Unix.

189

-

190

.. versionadded:: 3.3

191

-

192

-

193

.. data:: CLOCK_HIGHRES

194

-

195

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

196

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

197

is the nonadjustable, high-resolution clock.

198

-

199

Availability: Solaris.

200

-

201

.. versionadded:: 3.3

202

-

203

-

204

.. data:: CLOCK_MONOTONIC

205

-

206

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

207

starting point.

208

-

209

Availability: Unix.

210

-

211

.. versionadded:: 3.3

212

-

213

-

214

.. data:: CLOCK_MONOTONIC_RAW

215

-

216

`` -

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

217

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

218

-

219

Availability: Linux 2.6.28 or later.

220

-

221

.. versionadded:: 3.3

222

-

223

-

224

.. data:: CLOCK_PROCESS_CPUTIME_ID

225

-

226

High-resolution per-process timer from the CPU.

227

-

228

Availability: Unix.

229

-

230

.. versionadded:: 3.3

231

-

232

-

233

.. data:: CLOCK_REALTIME

234

-

235

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

236

privileges.

237

-

238

Availability: Unix.

239

-

240

.. versionadded:: 3.3

241

-

242

-

243

.. data:: CLOCK_THREAD_CPUTIME_ID

244

-

245

Thread-specific CPU-time clock.

184

Set the time of the specified clock clk_id. Currently,

185

`` +

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

246

186

247

187

` Availability: Unix.

248

188

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

257

197

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


`258`

`198`

``

`259`

`199`

``

`260`

``

`-

.. data:: daylight

`

`261`

``

`-`

`262`

``

`-

Nonzero if a DST timezone is defined.

`

`263`

``

`-`

`264`

``

`-`

`265`

`200`

`.. function:: get_clock_info(name)

`

`266`

`201`

``

`267`

`202`

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

`

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

`

`279`

`214`

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

280

215

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


`281`

`216`

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

`

`282`

``

`-

the clock value

`

``

`217`

`` +

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

``

`283`

`218`

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

284

219

``` False otherwise


`285`

`220`

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

``

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

`

`607`

`542`

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

``

`608`

`543`

` of the calendar date may be accessed as attributes.

`

`609`

`544`

``

`610`

``

`-

.. data:: timezone

`

`611`

``

`-`

`612`

``

`-

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

`

`613`

``

`-

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

`

`614`

``

`-`

`615`

``

`-`

`616`

``

`-

.. data:: tzname

`

`617`

``

`-`

`618`

``

`-

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

`

`619`

``

`-

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

`

`620`

``

`-

the second string should not be used.

`

`621`

``

`-`

`622`

`545`

``

`623`

`546`

`.. function:: tzset()

`

`624`

`547`

``

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

`

`703`

`626`

` ('EET', 'EEST')

`

`704`

`627`

``

`705`

`628`

``

``

`629`

`+

.. _time-clock-id-constants:

`

``

`630`

`+`

``

`631`

`+

Clock ID Constants

`

``

`632`

`+

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

`

``

`633`

`+`

``

`634`

`` +

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

``

``

`635`

`` +

:func:`clock_gettime`.

``

``

`636`

`+`

``

`637`

`+

.. data:: CLOCK_HIGHRES

`

``

`638`

`+`

``

`639`

``` +

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

640

hardware source, and may give close to nanosecond resolution.

641


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

642

+

643

Availability: Solaris.

644

+

645

.. versionadded:: 3.3

646

+

647

+

648

.. data:: CLOCK_MONOTONIC

649

+

650

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

651

starting point.

652

+

653

Availability: Unix.

654

+

655

.. versionadded:: 3.3

656

+

657

+

658

.. data:: CLOCK_MONOTONIC_RAW

659

+

660

`` +

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

661

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

662

+

663

Availability: Linux 2.6.28 or later.

664

+

665

.. versionadded:: 3.3

666

+

667

+

668

.. data:: CLOCK_PROCESS_CPUTIME_ID

669

+

670

High-resolution per-process timer from the CPU.

671

+

672

Availability: Unix.

673

+

674

.. versionadded:: 3.3

675

+

676

+

677

.. data:: CLOCK_THREAD_CPUTIME_ID

678

+

679

Thread-specific CPU-time clock.

680

+

681

Availability: Unix.

682

+

683

.. versionadded:: 3.3

684

+

685

+

686

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

687

`` +

:func:clock_settime.

688

+

689

.. data:: CLOCK_REALTIME

690

+

691

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

692

privileges.

693

+

694

Availability: Unix.

695

+

696

.. versionadded:: 3.3

697

+

698

+

699

.. _time-timezone-constants:

700

+

701

Timezone Constants

702

703

+

704

.. data:: altzone

705

+

706

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

707

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

708


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

709

+

710

.. data:: daylight

711

+

712

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

713

+

714

.. data:: timezone

715

+

716

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

717

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

718

+

719

.. data:: tzname

720

+

721

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

722

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

723

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

724

+

725

.. note::

726

+

727

`` +

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

728

`` +

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

729

`` +

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

730

`` +

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

731

`` +

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

732

+

733

+

706

734

`.. seealso::

707

735

708

736

`` Module :mod:datetime