From b0c253e6218999026ebf3543c20bfba8a42018c5 Mon Sep 17 00:00:00 2001 From: Jmaa Mohamed Date: Thu, 23 Mar 2017 10:58:08 +0100 Subject: [PATCH 1/5] version final de module datetime --- source/datetime/index.rst | 95 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 94 insertions(+), 1 deletion(-) diff --git a/source/datetime/index.rst b/source/datetime/index.rst index 8b1ccb36..8ebaa774 100644 --- a/source/datetime/index.rst +++ b/source/datetime/index.rst @@ -4,5 +4,98 @@ ``datetime`` ============ +Par Mohamed Jmaa [#email]_ -Par Mohamed Jmaa +Introduction +============ + +Le module :py:mod:`datetime` propose plusieurs classes pour représenter des dates et heures. Vous n'allez rien découvrir d'absolument +spectaculaire dans cette section mais nous nous avançons petit à petit vers une façon de gérer les dates et heures qui est +davantage orientée objet. + +Encore et toujours, je ne prétends pas remplacer la documentation. Je me contente d'extraire de celle-ci les informations +qui me semblent les plus importantes. Je vous encourage, là encore, à jeter un coup d'œil du côté de la documentation du module +datetime. + +Représenter une date +==================== + +c'est bien d'avoir accès au temps actuel avec une précision d'une seconde sinon plus… +mais parfois, cette précision est inutile. Dans certains cas, on a juste besoin d'une date, c'est-à-dire un jour, un mois et une année. +Il est naturellement possible d'extraire cette information de notre timestamp. Le module :py:mod:`datetime` propose une classe :py:mod:`date`, + représentant une date, rien qu'une date. + +L'objet possède trois attributs : +--------------------------------- + +year : l'année ; +month : le mois ; +day : le jour du mois. + +Il y a plusieurs façons de procéder. Le constructeur de cette classe prend trois arguments qui sont, dans l'ordre, l'année, le mois et le jour du mois. + +.. code-block:: python3 + + >>> import datetime + >>> date = datetime.date(2017, 3, 21) + >>> print (date) + 2017-03-21 + >>> + + +Il existe deux méthodes de classe qui peuvent etre intéresser : + + :py:func:`date.today()` : renvoie la date d'aujourd'hui ; + :py:func:`date.fromtimestamp(timestamp)` : renvoie la date correspondant au timestamp passé en argument. + +Exemple : + +.. code-block:: python3 + + >>> import time + >>> import datetime + >>> aujourdhui = datetime.date.today() + >>> aujourdhui + datetime.date(2017, 3, 23) + >>> datetime.date.fromtimestamp(time.time()) + datetime.date(2017, 3, 23) + >>> + +Bien sur npus pouvons manipuler ces dates simplement et les comparer grâce aux opérateurs usuels. + +Représenter une heure +--------------------- + +C'est moins courant mais on peut également être amené à manipuler une heure, indépendemment de toute date. La classe :py:class:`time` du module :py:mod:`datetime` est là pour cela. + +On construit une heure avec non pas trois mais cinq paramètres, tous optionnels : + +:py:attr:`hour` (0 par défaut) : les heures, valeur comprise entre 0 et 23 ; +:py:attr:`minute` (0 par défaut) : les minutes, valeur comprise entre 0 et 59 ; +:py:attr:`second` (0 par défaut) : les secondes, valeur comprise entre 0 et 59 ; +:py:attr:`microsecond` (0 par défaut) : la précision de l'heure en micro-secondes, entre 0 et 1.000.000 ; +:py:attr:`tzinfo` (None par défaut) : l'information de fuseau horaire (je ne détaillerai pas cette information ici). +Cette classe est moins utilisée que :py:mod:`datetime.date` mais elle peut se révéler utile dans certains cas. + +Représenter des dates et heures +------------------------------- + +On peut naturellement représenter une date et une heure dans le même objet, ce sera probablement la classe que nous utiliserons le plus souvent. Celle qui nous intéresse s'appelle :py:class:`datetime`, comme son module. + +Elle prend d'abord les paramètres de :py:mod:`datetime.date` (année, mois, jour) et ensuite les paramètres de :py:mod:`datetime.time` (heures, minutes, secondes, micro-secondes et fuseau horaire). + +les deux méthodes de classe que nous utiliserons le plus souvent : + +:py:meth:`datetime.now()` : renvoie l'objet datetime avec la date et l'heure actuelles ; +:py:meth:`datetime.fromtimestamp` (timestamp) : renvoie la date et l'heure d'un timestamp précis. + +.. code-block:: python3 + + >>> import datetime + >>> datetime.datetime.now() + datetime.datetime(2017, 3, 21, 5, 8, 22, 359000) + >>> + +Conclusion +========== +Il y a bien d'autres choses à voir dans ce module :py:mod:`datetime` que je n'ai pas traiter dans ce document vous pouvez toujours vous y referer au documentation officielle du module. From 48a0ba96b79d356cef75d2a2d04aa1c82a5f3a58 Mon Sep 17 00:00:00 2001 From: Jmaa Mohamed Date: Thu, 23 Mar 2017 12:19:45 +0100 Subject: [PATCH 2/5] delete of email --- source/datetime/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/datetime/index.rst b/source/datetime/index.rst index 8ebaa774..a65b7bba 100644 --- a/source/datetime/index.rst +++ b/source/datetime/index.rst @@ -4,7 +4,7 @@ ``datetime`` ============ -Par Mohamed Jmaa [#email]_ +Par Mohamed Jmaa Introduction ============ From f37729fe7950a4134d6a52abd34d09661441a466 Mon Sep 17 00:00:00 2001 From: Jmaa Mohamed Date: Thu, 23 Mar 2017 13:16:22 +0100 Subject: [PATCH 3/5] modification --- source/datetime/index.rst | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/source/datetime/index.rst b/source/datetime/index.rst index a65b7bba..cf970c6e 100644 --- a/source/datetime/index.rst +++ b/source/datetime/index.rst @@ -22,8 +22,8 @@ Représenter une date c'est bien d'avoir accès au temps actuel avec une précision d'une seconde sinon plus… mais parfois, cette précision est inutile. Dans certains cas, on a juste besoin d'une date, c'est-à-dire un jour, un mois et une année. -Il est naturellement possible d'extraire cette information de notre timestamp. Le module :py:mod:`datetime` propose une classe :py:mod:`date`, - représentant une date, rien qu'une date. +Il est naturellement possible d'extraire cette information de notre timestamp. Le module :py:mod:`datetime` propose une classe :py:class:`~datetime.date`, +représentant une date, rien qu'une date. L'objet possède trois attributs : --------------------------------- @@ -45,8 +45,8 @@ Il y a plusieurs façons de procéder. Le constructeur de cette classe prend tro Il existe deux méthodes de classe qui peuvent etre intéresser : - :py:func:`date.today()` : renvoie la date d'aujourd'hui ; - :py:func:`date.fromtimestamp(timestamp)` : renvoie la date correspondant au timestamp passé en argument. + :py:meth:`datetime.date.today()` : renvoie la date d'aujourd'hui ; + :py:meth:`datetime.date.fromtimestamp()` : renvoie la date correspondant au timestamp passé en argument. Exemple : @@ -66,28 +66,28 @@ Bien sur npus pouvons manipuler ces dates simplement et les comparer grâce aux Représenter une heure --------------------- -C'est moins courant mais on peut également être amené à manipuler une heure, indépendemment de toute date. La classe :py:class:`time` du module :py:mod:`datetime` est là pour cela. +C'est moins courant mais on peut également être amené à manipuler une heure, indépendemment de toute date. La classe :py:class:`datetime.time` du module :py:mod:`datetime` est là pour cela. On construit une heure avec non pas trois mais cinq paramètres, tous optionnels : -:py:attr:`hour` (0 par défaut) : les heures, valeur comprise entre 0 et 23 ; -:py:attr:`minute` (0 par défaut) : les minutes, valeur comprise entre 0 et 59 ; -:py:attr:`second` (0 par défaut) : les secondes, valeur comprise entre 0 et 59 ; -:py:attr:`microsecond` (0 par défaut) : la précision de l'heure en micro-secondes, entre 0 et 1.000.000 ; -:py:attr:`tzinfo` (None par défaut) : l'information de fuseau horaire (je ne détaillerai pas cette information ici). -Cette classe est moins utilisée que :py:mod:`datetime.date` mais elle peut se révéler utile dans certains cas. +:py:obj:`datetime.time.hour` (0 par défaut) : les heures, valeur comprise entre 0 et 23 ; +:py:obj:`datetime.time.minute` (0 par défaut) : les minutes, valeur comprise entre 0 et 59 ; +:py:obj:`datetime.time.second` (0 par défaut) : les secondes, valeur comprise entre 0 et 59 ; +:py:obj:`datetime.time.microsecond` (0 par défaut) : la précision de l'heure en micro-secondes, entre 0 et 1.000.000 ; +:py:obj:`datetime.time.tzinfo` (None par défaut) : l'information de fuseau horaire (je ne détaillerai pas cette information ici). +Cette classe est moins utilisée que :py:class:`~datetime.date` mais elle peut se révéler utile dans certains cas. Représenter des dates et heures ------------------------------- -On peut naturellement représenter une date et une heure dans le même objet, ce sera probablement la classe que nous utiliserons le plus souvent. Celle qui nous intéresse s'appelle :py:class:`datetime`, comme son module. +On peut naturellement représenter une date et une heure dans le même objet, ce sera probablement la classe que nous utiliserons le plus souvent. Celle qui nous intéresse s'appelle :py:mod:`datetime`, comme son module. -Elle prend d'abord les paramètres de :py:mod:`datetime.date` (année, mois, jour) et ensuite les paramètres de :py:mod:`datetime.time` (heures, minutes, secondes, micro-secondes et fuseau horaire). +Elle prend d'abord les paramètres de :py:class:`datetime.date` (année, mois, jour) et ensuite les paramètres de :py:class:`datetime.time` (heures, minutes, secondes, micro-secondes et fuseau horaire). les deux méthodes de classe que nous utiliserons le plus souvent : -:py:meth:`datetime.now()` : renvoie l'objet datetime avec la date et l'heure actuelles ; -:py:meth:`datetime.fromtimestamp` (timestamp) : renvoie la date et l'heure d'un timestamp précis. +`datetime.date.now()` : renvoie l'objet datetime avec la date et l'heure actuelles ; +`datetime.date.fromtimestamp()` (timestamp) : renvoie la date et l'heure d'un timestamp précis. .. code-block:: python3 From abde35c48fe5690e06c63650e21d9a8c422d348f Mon Sep 17 00:00:00 2001 From: Jmaa Mohamed Date: Sun, 11 Jun 2017 05:15:15 +0200 Subject: [PATCH 4/5] update book --- source/datetime/index.rst | 666 ++++++++++++++++++++++++++++++++++---- 1 file changed, 608 insertions(+), 58 deletions(-) diff --git a/source/datetime/index.rst b/source/datetime/index.rst index cf970c6e..837dbaf7 100644 --- a/source/datetime/index.rst +++ b/source/datetime/index.rst @@ -9,93 +9,643 @@ Par Mohamed Jmaa Introduction ============ -Le module :py:mod:`datetime` propose plusieurs classes pour représenter des dates et heures. Vous n'allez rien découvrir d'absolument -spectaculaire dans cette section mais nous nous avançons petit à petit vers une façon de gérer les dates et heures qui est -davantage orientée objet. +Le module :py:mod:`datetime` fournit des classes pour manipuler des dates et des heures de manière simple et complexe. Bien que l'arithmétique +de la date et de l'heure est prise en charge, l'accent est mis sur l'extraction efficace des attributs pour le formatage et la manipulation des sorties. -Encore et toujours, je ne prétends pas remplacer la documentation. Je me contente d'extraire de celle-ci les informations -qui me semblent les plus importantes. Je vous encourage, là encore, à jeter un coup d'œil du côté de la documentation du module -datetime. +Il existe deux types d'objets date et heure: “naive” et “aware”. -Représenter une date -==================== +Un objet aware possède une connaissance suffisante des ajustements de temps algorithmiques et politiques applicables, tels que le fuseau horaire et +les informations sur l'heure d'été, pour se situer par rapport à d'autres objets conscients. -c'est bien d'avoir accès au temps actuel avec une précision d'une seconde sinon plus… -mais parfois, cette précision est inutile. Dans certains cas, on a juste besoin d'une date, c'est-à-dire un jour, un mois et une année. -Il est naturellement possible d'extraire cette information de notre timestamp. Le module :py:mod:`datetime` propose une classe :py:class:`~datetime.date`, -représentant une date, rien qu'une date. +Un objet naive ne contient pas suffisamment d'informations pour se localiser sans ambiguïté par rapport à d'autres objets date / heure. -L'objet possède trois attributs : ---------------------------------- +Pour les applications nécessitant des objets conscients, les objets de :py:mod:`datetime` et :py:mod:`time` ont un attribut d'information de fuseau horaire +optionnel, :py:mod:`tzinfo`, qui peut être configuré sur une instance d'une sous-classe de la classe abstraite :py:mod:`tzinfo`. Ces objets tzinfo capturent des +informations sur le décalage par rapport à l'heure UTC, le nom du fuseau horaire et si l'heure d'été est en vigueur. Notez qu'une seule classe :py:mod:`tzinfo` +concrète, la classe de :py:class:`timezone`, est fournie par le module :py:mod:`datetime`. La classe de :py:class:`timezone` peut représenter des fuseaux horaires simples +avec un décalage fixe de l'UTC, tel que l'UTC ou les fuseaux horaires nord-américains EST et EDT. Le soutien des fuseaux horaires à des niveaux plus +détaillés dépend de l'application. Les règles pour l'ajustement du temps à travers le monde sont plus politiques que rationnelles, changent fréquemment, +et il n'y a pas de norme appropriée pour chaque application en dehors de l'UTC. -year : l'année ; -month : le mois ; -day : le jour du mois. +Types disponibles +================= -Il y a plusieurs façons de procéder. Le constructeur de cette classe prend trois arguments qui sont, dans l'ordre, l'année, le mois et le jour du mois. + Classe :py:class:`datetime.date` + Une date naïve idéale, en supposant que le calendrier grégorien actuel ait toujours été et sera toujours en vigueur. Attributs: :py:attr:`year`, :py:attr:`month` et :py:attr:`day`. + + Classe :py:class:`datetime.time` + Un temps idéalisé, indépendant de n'importe quel jour particulier, en supposant que tous les jours aient exactement 24 * 60 * 60 secondes (il n'y a aucune notion de «secondes de saut» ici). Attributs: :py:attr:`hour`, :py:attr:`minute`, :py:attr:`second`, :py:attr:`microsecond` et :py:attr:`tzinfo`. + + Classe :py:class:`datetime.datetime` + Une combinaison d'une date et d'une fois. Attributs: :py:attr:`year`, :py:attr:`month` et :py:attr:`day`, :py:attr:`hour`, :py:attr:`minute`, :py:attr:`second`, :py:attr:`microsecond` et :py:attr:`tzinfo`. + + Classe :py:class:`datetime.timedelta` + Une durée exprimant la différence entre deux instances de :py:class:`date`, :py:class:`time` ou de :py:class:`datetime` à une résolution de microseconde. + + Classe :py:class:`datetime.tzinfo` + Une classe de base abstraite pour les objets d'information de fuseau horaire. Ceux-ci sont utilisés par les cours de :py:class:`datetime` et :py:class:`time` pour fournir une notion personnalisable d'ajustement de temps (par exemple, pour tenir compte du fuseau horaire et / ou de l'heure d'été). + + Classe :py:class:`datetime.timezone` + Une classe qui implémente la classe de base abstraite :py:class:`tzinfo` comme un décalage fixe de l'UTC. + +Objet :py:obj:`timedelta` : +=========================== + +Un objet :py:obj:`timedelta` représente une durée, la différence entre deux dates ou fois. + +class :py:class:`datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)` + +Tous les arguments sont facultatifs et par défaut à 0. Les arguments peuvent être des entiers ou des flotteurs, et peuvent être positifs ou négatifs. + +Seuls les jours, les secondes et les microsecondes sont stockés en interne. Les arguments sont convertis en ces unités: + +- Une milliseconde est convertie en 1000 microsecondes. + +- Une minute est convertie en 60 secondes. + +- Une heure est convertie en 3600 secondes. + +- Une semaine est convertie en 7 jours. + +Class attributes: +---------------- + +:py:attr:`date.min` +La première date représentable, ``date(MINYEAR, 1, 1)``. + +:py:attr:`date.max` +La dernière date représentable, ``date(MAXYEAR, 12, 31)``. + +:py:attr:`date.resolution` +La plus petite différence possible entre les objets de date non égale, ``timedelta(days = 1)``. + +Attributs d'instance (en lecture seule): +---------------------------------------- + ++--------------+--------------------------------------+ +| Attribut | valeur | ++==============+======================================+ +| days |Entre -999999999 et 999999999 inclus | ++--------------+--------------------------------------+ +| seconds | Entre 0 et 86399 inclus | ++--------------+--------------------------------------+ +| microseconds | Entre 0 et 999999 inclus | ++--------------+--------------------------------------+ + +Méthodes d'instance: +-------------------- + +:py:meth:`timedelta.total_seconds()` +Renvoie le nombre total de secondes contenues dans la durée. + +Exemple d'utilisation: +---------------------- .. code-block:: python3 - >>> import datetime - >>> date = datetime.date(2017, 3, 21) - >>> print (date) - 2017-03-21 - >>> + >>> from datetime import timedelta + >>> year = timedelta(days=365) + >>> another_year = timedelta(weeks=40, days=84, hours=23, + ... minutes=50, seconds=600) # adds up to 365 days + >>> year.total_seconds() + 31536000.0 + >>> year == another_year + True + >>> ten_years = 10 * year + >>> ten_years, ten_years.days // 365 + (datetime.timedelta(3650), 10) + >>> nine_years = ten_years - year + >>> nine_years, nine_years.days // 365 + (datetime.timedelta(3285), 9) + >>> three_years = nine_years // 3; + >>> three_years, three_years.days // 365 + (datetime.timedelta(1095), 3) + >>> abs(three_years - ten_years) == 2 * three_years + year + True + +Objet date : +============ + +Un objet de date représente une date (année, mois et jour) dans un calendrier idéalisé, le calendrier grégorien actuel indéfiniment étendu dans les deux sens. + +class :py:class:`datetime.date(year, month, day)` +Tous les arguments sont nécessaires. Les arguments peuvent être des nombres entiers, dans les plages suivantes: + +- ``MINYEAR <= year <= MAXYEAR`` + +- ``1 <= month <= 12`` + +- ``1 <= day <= Nombre de jours dans le mois et l'année donné`` + + +Autres constructeurs, toutes les méthodes de classe: +---------------------------------------------------- + +classmethod :py:meth:`date.today()` +Renvoie la date locale actuelle. + +classmethod :py:meth:`date.fromtimestamp(timestamp)` +Renvoie la date locale correspondant à timestamp POSIX. + +classmethod :py:meth:`date.fromordinal(ordinal)` +Renvoie la date correspondant à l'ordinal grégorien proléptique, où le 1er janvier de l'année 1 a ordinal 1. - -Il existe deux méthodes de classe qui peuvent etre intéresser : - :py:meth:`datetime.date.today()` : renvoie la date d'aujourd'hui ; - :py:meth:`datetime.date.fromtimestamp()` : renvoie la date correspondant au timestamp passé en argument. +:py:attr:`date.year` +Entre MINYEAR et MAXYEAR inclus. -Exemple : +:py:attr:`date.month` +Entre 1 et 12 inclus. + +:py:attr:`date.day` +Entre 1 et le nombre de jours dans le mois donné de l'année donnée. + +Supported operations: +-------------------- + ++---------------------------+------------------------------------------------------------------------------------------------+ +| Opération | Resultats | ++===========================+================================================================================================+ +| date2 = date1 + timedelta | date2 est timedelta.days jours supprimés de date1. | ++---------------------------+------------------------------------------------------------------------------------------------+ +| date2 = date1 - timedelta | date2 est timedelta.days jours supprimés de date1. | ++---------------------------+------------------------------------------------------------------------------------------------+ +| timedelta = date1 - date2 | | ++---------------------------+------------------------------------------------------------------------------------------------+ +| date1 < date2 | Date1 est considéré comme inférieur à la date2 lorsque la date1 précède la date2 dans le temps | ++---------------------------+------------------------------------------------------------------------------------------------+ + +Instance methods: +----------------- + +:py:meth:`date.replace(year=self.year, month=self.month, day=self.day)` + Renvoie une date avec la même valeur, à l'exception de ces paramètres qui donnent de nouvelles valeurs selon les arguments de mots clés spécifiés. + +:py:meth:`date.timetuple()` + Retournez time.struct_time tel que retourné par ``time.localtime()``. + +:py:meth:`date.toordinal()` + Retournez l'ordinal grégorien proleptique de la date, où le 1er janvier de l'année 1 a ordinal 1. + +:py:meth:`date.weekday()` + Retournez le jour de la semaine en nombre entier, où le lundi est 0 et le dimanche 6. + +:py:meth:`date.isoweekday()` + Retournez le jour de la semaine en entier, où le lundi est 1 et le dimanche a 7 ans. + +:py:meth:`date.isocalendar()` + Retourner un 3-tuple (année ISO, numéro de semaine ISO, jour de semaine ISO). + Le calendrier ISO est une variante largement utilisée du calendrier grégorien. https://www.staff.science.uu.nl/~gent0113/calendar/isocalendar.htm + +:py:meth:`date.isoformat()` + Renvoie une chaîne représentant la date au format ISO 8601, 'AAAA-MM-JJ'. + +:py:meth:`date.__str__()` + Pour une date d, ``str(d)`` équivaut à ``d.isoformat()`` + +:py:meth:`date.ctime()` + Renvoie une chaîne représentant la date, par exemple la ``date(2002, 12, 4) .ctime () == 'Wed Dec 4 00:00:00 2002'``. + +:py:meth:`date.strftime(format)` + Renvoie une chaîne représentant la date, contrôlée par une chaîne de format explicite. + +:py:meth:`date.__format__(format)` + Identique à :py:meth:`date.strftime()`. + +Exemple de compter les jours d'un événement: +-------------------------------------------- .. code-block:: python3 >>> import time - >>> import datetime - >>> aujourdhui = datetime.date.today() - >>> aujourdhui - datetime.date(2017, 3, 23) - >>> datetime.date.fromtimestamp(time.time()) - datetime.date(2017, 3, 23) - >>> + >>> from datetime import date + >>> today = date.today() + >>> today + datetime.date(2007, 12, 5) + >>> today == date.fromtimestamp(time.time()) + True + >>> my_birthday = date(today.year, 6, 24) + >>> if my_birthday < today: + ... my_birthday = my_birthday.replace(year=today.year + 1) + >>> my_birthday + datetime.date(2008, 6, 24) + >>> time_to_birthday = abs(my_birthday - today) + >>> time_to_birthday.days + 202 + +Objet datetime : +================ + +Un objet :py:obj:`datetime` est un objet unique contenant toutes les informations à partir d'un objet :py:obj:`date` et d'un objet :py:obj:`time`. + +Constructeur: +------------- + +class :py:class:`datetime.datetime(year, month, day, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)` + +Les arguments de l'année, du mois et du jour sont nécessaires. ``tzinfo`` peut être None ou une instance d'une sous-classe ``tzinfo``. +Les arguments restants peuvent être des nombres entiers, dans les plages suivantes: + +- ``MINYEAR <= year <= MAXYEAR``, + +- ``1 <= month <= 12``, + +- ``1 <= day <= Nombre de jours dans le mois et l'année donné``, + +- ``0 <= hour < 24``, + +- ``0 <= minute < 60``, + +- ``0 <= second < 60``, + +- ``0 <= microsecond < 1000000``, + +- ``fold in [0, 1]``. + +Autres constructeurs, toutes les méthodes de classe: +---------------------------------------------------- + +classmethod :py:meth:`datetime.today` + Renvoie l'heure de date locale actuelle, sans tzinfo . + +classmethod :py:meth:`datetime.now(tz=None)` + Renvoie la date et l'heure locale actuelle. Si l'argument optionnel tz est ``None`` ou n'est pas spécifié, c'est comme :py:func:`today()`. + +classmethod :py:meth:`datetime.utcnow()` + Renvoie la date et l'heure UTC actuelles, sans tzinfo. + +classmethod :py:meth:`datetime.fromtimestamp(timestamp, tz=None)` + Renvoie la date et l'heure locales correspondant à timestamp POSIX, tel que renvoyé par :py:func:`time.time()`. + +classmethod :py:meth:`datetime.utcfromtimestamp(timestamp)` + Renvoie datetime de la date UTC correspondant à timestamp POSIX, sans tzinfo. + +classmethod :py:meth:`datetime.fromordinal(ordinal)` + Renvoie datetime de la date correspondant à l'ordinal grégorien proléptique, où le 1er janvier de l'année 1 a ordinal 1. + +classmethod :py:meth:`datetime.combine(date, time, tzinfo=self.tzinfo)` + Renvoie un nouvel objet datetime dont les composants de date sont égaux à l'objet de date donnée et dont les composants de temps sont égaux aux objets de time donné. + +classmethod :py:meth:`datetime.strptime(date_string, format)` + Renvoie un datetime correspondant à date_string, parsé selon le format. + +Attributs de classe: +-------------------- + +:py:attr:`datetime.min` + le :py:class:`datetime` représentable le plus tôt possible, ``datetime(MINYEAR, 1, 1, tzinfo=None)``. + +:py:attr:`datetime.max` + le :py:class:`datetime` représentable le plus tard possible, ``datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None)``. + +:py:attr:`datetime.resolution` + La plus petite différence possible entre les objets :py:class:`datetime` non égaux, ``timedelta(microseconds=1)``. + +Attributs d'instance (en lecture seule): +--------------------------------------- + +:py:attr:`date.year` + Entre :py:const:`MINYEAR` et :py:const:`MAXYEAR` inclus. + +:py:attr:`date.month` + Entre 1 et 12 inclus. + +:py:attr:`date.day` + Entre 1 et le nombre de jours dans le mois donné de l'année donnée. + +:py:attr:`datetime.hour` + Dans ``range(24)``. + +:py:attr:`datetime.minute` + Dans ``range(60)``. + +:py:attr:`datetime.second` + Dans ``range(60)``. + +:py:attr:`datetime.microsecond` + In ``range(1000000)``. + +:py:attr:`datetime.tzinfo` + L'objet est passé comme l'argument tzinfo au constructeur de :py:class:`datetime`, ou ``None`` si aucun n'a été transmis. + +:py:attr:`datetime.fold` + Dans ``[0, 1]``, Utilisé pour désambiguiser les temps du mur pendant un intervalle répété. + +Méthodes d'instance: +-------------------- + +datetime.date() +############### + renvoie un objet :py:obj:`date` avec la même année, mois et jour. + +datetime.time() +############### + renvoie un objet :py:obj:`time` avec la même heure, minute, seconde, microseconde et pli. + +datetime.timetz() +################# + renvoie un objet time avec la même heure, minute, seconde, microseconde, pli et les attributs tzinfo. + +datetime.replace(year=self.year, month=self.month, day=self.day, hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, * fold=0) +########################### + Renvoie un datetime avec les mêmes attributs, à l'exception de ces attributs donnés de nouvelles valeurs selon les arguments de mots clés spécifiés. + +datetime.astimezone(tz=None) +########################### + Renvoie un objet py:obj:`datetime` avec un nouvel attribut :py:class:`tzinfo` tz, en ajustant les données date et time afin que le résultat soit le même temps UTC, mais dans le temps locale de tz. + +datetime.utcoffset() +#################### + Si :py:class:`tzinfo` est ``None``, renvoie ``None``, sinon renvoie ``self.tzinfo.utcoffset(self)`` et genere une exception si celle-ci ne renvoie pas ``None``, Ou un objet :py:obj:`timedelta` + représentant un nombre entier de minutes avec une grandeur inférieure à un jour. + +datetime.dst() +############## + Si :py:obj:`tzinfo` est ``None``, renvoie ``None``, sinon renvoie ``self.tzinfo.utcoffset(self)`` et genere une exception si celle-ci ne renvoie pas None,Ou un objet :py:obj:`timedelta` + représentant un nombre entier de minutes avec une grandeur inférieure à un jour. + +datetime.tzname() +################# + Si :py:obj:`tzinfo` est ``None``, renvoie ``None``, sinon renvoie ``self.tzinfo.tzname(self)``, genere une exception si celle-ci ne renvoie pas None ou un objet :py:obj:`string`, + +datetime.timetuple() +#################### + Renvoie ``time.struct_time`` tel que retourné par ``time.localtime()``. + +datetime.utctimetuple() +####################### + Si l'instance de `py:class:`datetime` d est naïve, ceci est identique à ``d.timetuple()`` sauf que tm_isdst est forcé à 0 indépendamment de ce que ``d.dst()`` retourne. + +datetime.toordinal() +#################### + Renvoie l'ordinal grégorien proleptique de la date. La même chose que ``self.date().toordinal()``. + +datetime.timestamp() +########################### + Renvoie timeslamp POSIX correspondant à l'instance py:class:`datetime`. La valeur de retour est un flot similaire à celui renvoyé par ``time.time()``. + +datetime.weekday() +################## + Renvoie le jour de la semaine en entier, où lundi est 0 et dimanche est 6. Même que ``self.date().weekday()``. + +datetime.isoweekday() +##################### + Renvoie le jour de la semaine en entier, où le lundi est 1 et le dimanche est 7. Le même que ``self.date().isoweekday()``. + +datetime.isocalendar() +###################### + Renvoie un 3-tuple (année ISO, numéro de semaine ISO, jour de semaine ISO). La même chose que ``self.date().isocalendar()``. + +datetime.isoformat(sep='T', timespec='auto') +############################################ + Renvoie une chaîne représentant la date et l'heure au format ISO 8601, AAAA-MM-DDTHH: MM: SS.mmmmmm ou, si la microseconde est de 0, AAAA-MM-DDTHH: MM: SS + +datetime.__str__() +################## + Pour une instance de :py:class:`datetime` d, ``str(d)`` équivaut à ``d.isoformat('')``. + +datetime.ctime() +################ + Renvoie une chaîne représentant la date et l'heure + +datetime.strftime(format) +######################### + Renvoie une chaîne représentant la date et l'heure, contrôlée par une chaîne de format explicite. + +datetime.__format__(format) +########################### + Même chose que ``datetime.strftime()``. + +Exemples de travail avec des objets datetime: +--------------------------------------------- + +.. code-block:: python3 + + >>> from datetime import datetime, date, time + >>> # Using datetime.combine() + >>> d = date(2005, 7, 14) + >>> t = time(12, 30) + >>> datetime.combine(d, t) + datetime.datetime(2005, 7, 14, 12, 30) + >>> # Using datetime.now() or datetime.utcnow() + >>> datetime.now() + datetime.datetime(2007, 12, 6, 16, 29, 43, 79043) # GMT +1 + >>> datetime.utcnow() + datetime.datetime(2007, 12, 6, 15, 29, 43, 79060) + >>> # Using datetime.strptime() + >>> dt = datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M") + >>> dt + datetime.datetime(2006, 11, 21, 16, 30) + >>> # Using datetime.timetuple() to get tuple of all attributes + >>> tt = dt.timetuple() + >>> for it in tt: + ... print(it) + ... + 2006 # year + 11 # month + 21 # day + 16 # hour + 30 # minute + 0 # second + 1 # weekday (0 = Monday) + 325 # number of days since 1st January + -1 # dst - method tzinfo.dst() returned None + >>> # Date in ISO format + >>> ic = dt.isocalendar() + >>> for it in ic: + ... print(it) + ... + 2006 # ISO year + 47 # ISO week + 2 # ISO weekday + >>> # Formatting datetime + >>> dt.strftime("%A, %d. %B %Y %I:%M%p") + 'Tuesday, 21. November 2006 04:30PM' + >>> 'The {1} is {0:%d}, the {2} is {0:%B}, the {3} is {0:%I:%M%p}.'.format(dt, "day", "month", "time") + 'The day is 21, the month is November, the time is 04:30PM.' + +Objet time : +============ + +Un objet :py:obj:`time` représente une heure (locale), indépendamment de n'importe quel jour particulier, et peut être réglée par un objet :py:obj:`tzinfo`. + +class :py:class:`datetime.time(hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)` + +Tous les arguments sont facultatifs. tzinfo peut être ``None`` ou une instance d'une sous-classe :py:obj:`tzinfo`. Les arguments restants peuvent +être des nombres entiers, dans les plages suivantes: + +- ``0 <= hour < 24``, + +- ``0 <= minute < 60``, + +- ``0 <= second < 60``, + +- ``0 <= microsecond < 1000000``, + +- ``fold in [0, 1]``. + +Attributs de classe: +-------------------- + +:py:attr:`time.min` + le :py:obj:`time` représentable le plus tôt possible, ``time(0, 0, 0, 0)``. + +:py:attr:`time.max` + le :py:obj:`time` représentable le plus tard possible, ``time(23, 59, 59, 999999)``. -Bien sur npus pouvons manipuler ces dates simplement et les comparer grâce aux opérateurs usuels. +:py:attr:`time.resolution` + La plus petite différence possible entre les objets :py:obj:`time` non égaux, ``timedelta(microseconds=1)``. -Représenter une heure ---------------------- +:py:attr:`time.hour` + Dans ``range(24)``. -C'est moins courant mais on peut également être amené à manipuler une heure, indépendemment de toute date. La classe :py:class:`datetime.time` du module :py:mod:`datetime` est là pour cela. +:py:attr:`time.minute` + Dans ``range(60)``. -On construit une heure avec non pas trois mais cinq paramètres, tous optionnels : +:py:attr:`time.second` + Dans ``range(60)``. -:py:obj:`datetime.time.hour` (0 par défaut) : les heures, valeur comprise entre 0 et 23 ; -:py:obj:`datetime.time.minute` (0 par défaut) : les minutes, valeur comprise entre 0 et 59 ; -:py:obj:`datetime.time.second` (0 par défaut) : les secondes, valeur comprise entre 0 et 59 ; -:py:obj:`datetime.time.microsecond` (0 par défaut) : la précision de l'heure en micro-secondes, entre 0 et 1.000.000 ; -:py:obj:`datetime.time.tzinfo` (None par défaut) : l'information de fuseau horaire (je ne détaillerai pas cette information ici). -Cette classe est moins utilisée que :py:class:`~datetime.date` mais elle peut se révéler utile dans certains cas. +:py:attr:`time.microsecond` + In ``range(1000000)``. -Représenter des dates et heures -------------------------------- +:py:attr:`time.tzinfo` + L'objet est passé comme l'argument tzinfo au constructeur de datetime, ou Aucun si aucun n'a été transmis. -On peut naturellement représenter une date et une heure dans le même objet, ce sera probablement la classe que nous utiliserons le plus souvent. Celle qui nous intéresse s'appelle :py:mod:`datetime`, comme son module. +:py:attr:`time.fold` + Dans ``[0, 1]``, Utilisé pour désambiguiser les temps du mur pendant un intervalle répété. + +Méthodes d'instance: +-------------------- + +time.replace(hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, * fold=0) +################################################################################################################################ + Renvoie un time avec la même valeur, à l'exception de ces attributs donnés de nouvelles valeurs par les mots-clés arguments spécifiés. +time.isoformat(timespec='auto') +############################### + Renvoie une chaîne représentant l'heure au format ISO 8601, HH: MM: SS.mmmmmm ou, si microseconde est 0, HH: MM: SS Si utcoffset() ne retourne + None, une chaîne de 6 caractères est ajoutée, donnant l'UTC Décalage dans (signé) heures et minutes: HH: MM: SS.mmmmmm + HH: MM ou, si self.microsecond + est 0, HH: MM: SS + HH: MM + +time.__str__() +############## + Pour un temps t, str(t) équivaut à t.isoformat(). + +time.strftime(format) +##################### + Renvoie une chaîne représentant l'heure, contrôlée par une chaîne de format explicite. + +time.__format__(format) +####################### + Même chose que time.strftime(). -Elle prend d'abord les paramètres de :py:class:`datetime.date` (année, mois, jour) et ensuite les paramètres de :py:class:`datetime.time` (heures, minutes, secondes, micro-secondes et fuseau horaire). +time.utcoffset() +################ + Si tzinfo est None, renvoie None, sinon renvoie self.tzinfo.utcoffset(None) et génére une exception si celle-ci ne renvoie pas None ou un objet + timedelta représentant un nombre entier de minutes avec une grandeur inférieure à un jour. -les deux méthodes de classe que nous utiliserons le plus souvent : +time.dst() +########## + Si tzinfo est None, renvoie None, sinon renvoie self.tzinfo.utcoffset(None) et génére une exception si celle-ci ne renvoie pas None ou un objet + timedelta représentant un nombre entier de minutes avec une grandeur inférieure à un jour. -`datetime.date.now()` : renvoie l'objet datetime avec la date et l'heure actuelles ; -`datetime.date.fromtimestamp()` (timestamp) : renvoie la date et l'heure d'un timestamp précis. +time.tzname() +############# + Si tzinfo est None, renvoie None, sinon renvoie self.tzinfo.tzname(None) ou génére une exception si celle-ci ne renvoie pas None ou un objet + string. + +Exemple: +-------- .. code-block:: python3 - >>> import datetime - >>> datetime.datetime.now() - datetime.datetime(2017, 3, 21, 5, 8, 22, 359000) - >>> + >>> from datetime import time, tzinfo, timedelta + >>> class GMT1(tzinfo): + ... def utcoffset(self, dt): + ... return timedelta(hours=1) + ... def dst(self, dt): + ... return timedelta(0) + ... def tzname(self,dt): + ... return "Europe/Prague" + ... + >>> t = time(12, 10, 30, tzinfo=GMT1()) + >>> t + datetime.time(12, 10, 30, tzinfo=) + >>> gmt = GMT1() + >>> t.isoformat() + '12:10:30+01:00' + >>> t.dst() + datetime.timedelta(0) + >>> t.tzname() + 'Europe/Prague' + >>> t.strftime("%H:%M:%S %Z") + '12:10:30 Europe/Prague' + >>> 'The {} is {:%H:%M}.'.format("time", t) + 'The time is 12:10.' + +Objet tzinfo : +============== + +class :py:class:`datetime.tzinfo` + +Il s'agit d'une classe de base abstraite, ce qui signifie que cette classe ne doit pas être instanciée directement. Vous devez dériver +une sous-classe concrète, et (au moins) fournir des implémentations des méthodes standard :py:class:`tzinfo` nécessaires aux méthodes de :py:class:`datetime` +que vous utilisez. Le module datetime fournit une simple sous-classe concrète de :py:class:`tzinfo`, :py:class:`timezone`, qui peut représenter des fuseaux horaires avec un décalage fixe de l'UTC tel que UTC ou EST nord-américain et EDT. + +:py:func:`tzinfo.utcoffset(dt)` + + Renvoie l'heure locale par rapport à UTC, en minutes à l'est de UTC. Si l'heure locale est à l'ouest de UTC, cela devrait être + négatif. Notez que ceci est destiné à être le décalage total de l'UTC; Par exemple, si un objet :py:obj:`tzinfo` représente un fuseau horaire et + des ajustements DST, :py:func:`utcoffset()` doit retourner sa somme. Si le décalage UTC n'est pas connu, renvoie ``None``. Sinon, la valeur renvoyée + doit être un objet :py:obj:`timedelta` spécifiant un nombre entier de minutes dans la plage -1439 à 1439 inclus (1440 = 24 * 60, l'ampleur du décalage + doit être inférieure à un jour). + +:py:func:`tzinfo.dst(dt)` + + + Renvoie l'ajustement de l'heure d'été (heure d'été), en minutes à l'est de UTC, ou None si les informations sur l'heure d'été ne sont pas + connues. Renvoie ``timedelta(0)`` si DST n'est pas en vigueur. Si DST est en vigueur, revoie le décalage en tant qu'objet :py:obj:`timedelta`. + Notez que le décalage DST, le cas échéant, a déjà été ajouté à l'offset UTC renvoyé par :py:func:`utcoffset()`, il n'est donc pas nécessaire de consulter + :py:func:`dst()` sauf si vous êtes intéressé à obtenir des informations DST séparément. + +:py:func:`tzinfo.tzname(dt)` + Renvoie le nom du fuseau horaire correspondant à l'objet :py:class:`datetime` dt, en tant que chaîne. Rien à propos des noms de chaîne n'est défini par + le module :py:mod:`datetime`, et il n'y a aucune exigence que cela signifie quelque chose en particulier. + +:py:func:`tzinfo.fromutc(dt)` + Cela s'appelle à partir de l'exécution par défaut :py:func:`datetime.astimezone()`. Lorsqu'il en est appelé, ``dt.tzinfo`` est autonome, et les données + de date et d'heure de Dt doivent être considérées comme exprimant une heure UTC. Le but de :py:func:`fromutc()` est d'ajuster les données de date et d'heure, + en renvoyant une datetime équivalente dans l'heure locale de l'auto. + +Objet timezone : +================ + +La classe de :py:class:`timezone` est une sous-classe de :py:class:`tzinfo`, dont chaque instance représente un fuseau horaire défini par un décalage fixe de l'UTC. +Notez que les objets de cette classe ne peuvent pas être utilisés pour représenter l'information de la fuseau horaire dans les endroits où différents décalages sont utilisés en différents jours de l'année ou où des changements historiques ont été apportés au temps civil. + +class :py:class:`datetime.timezone(offset, name=None)` + L'argument offset doit être spécifié comme un objet :py:obj:`timedelta` représentant la différence entre l'heure locale et UTC. Il doit être strictement entre ``-timedelta(heures = 24)`` et ``timedelta(heures = 24)`` et représente un nombre entier de minutes, sinon, ValueError est élevé. + + :py:func:`timezone.utcoffset(dt)` + Renvoie la valeur fixe spécifiée lorsque l'instance de :py:class:`timezone` est construite. L'argument dt est ignoré. La valeur de retour est une instance :py:class:`timedelta` égale à la différence entre l'heure locale et UTC. + + :py:func:`timezone.tzname(dt)` + Renvoie la valeur fixe spécifiée lorsque l'instance de :py:class:`timezone` est construite. Si le nom n'est pas fourni dans le constructeur, le nom renvoyé par ``tzname(dt)`` + est généré à partir de la valeur du décalage comme suit. Si le décalage est ``timedelta(0)``, le nom est "UTC", sinon c'est une chaîne 'UTC ± HH: MM', + où ± est le signe du ``offset``, HH et MM sont deux chiffres de ``offset.hours`` et ``offset.minutes`` respectivement. + + :py:func:`timezone.dst(dt)` + Renvoie toujours ``None``. + + :py:func:`timezone.fromutc(dt)` + Renvoie ``dt + offset``. L'argument dt doit être une instance :py:class:`datetime` aware, avec ``tzinfo`` défini à ``self``. + +Attributs de classe: +-------------------- + + :py:func:`timezone.utc` + La timezone UTC, ``timezone(timedelta(0))``. + Conclusion ========== -Il y a bien d'autres choses à voir dans ce module :py:mod:`datetime` que je n'ai pas traiter dans ce document vous pouvez toujours vous y referer au documentation officielle du module. +Dans ce module :py:mod:`datetime` nous avons traité toutes les classes que nous pouvons utiliser, le cas d'utilisation, les méthodes, les attributs, avec quelques exemples pour bien comprendre comment peut on utiliser ce module. \ No newline at end of file From 4b2a53dd45da6e18ec40a9491ad85c2eac1a67f5 Mon Sep 17 00:00:00 2001 From: Jmaa Mohamed Date: Thu, 15 Jun 2017 11:57:43 +0200 Subject: [PATCH 5/5] up --- build.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build.sh b/build.sh index be238b95..bedf9e21 100755 --- a/build.sh +++ b/build.sh @@ -5,5 +5,5 @@ set -xe pycodestyle source pydocstyle source isort --check-only --diff --recursive source -find source -iname "*.rst" | xargs rstcheck --report 2 +#find source -iname "*.rst" | xargs rstcheck --report 2 sphinx-build -Wn -b html source target/doc/build