Add or translate some docstrings in logs/

logs/forms.py

@@ -53,6 +53,15 @@ CHOICES_TYPE = (
 
 
 def all_classes(module):
+    """Get the list of all class names of the module.
+
+    Args:
+        module: the module in which to retrieve classes.
+
+    Returns:
+        A list containing the names of all classes that are defined in
+        the module.
+    """
     classes = []
 
     for name, obj in inspect.getmembers(module):
@@ -63,8 +72,16 @@ def all_classes(module):
 
 
 def classes_for_action_type(action_type):
-    """Return the list of class names to be displayed for a
+    """Get the list of class names to be displayed for a given action type
-    given actions type filter"""
+    filter.
+
+    Args:
+        action_type: the string used to filter the class names.
+
+    Returns:
+        A list containing the class names corresponding to the action type
+        filter.
+    """
     if action_type == "users":
         return [
             users.models.User.__name__,
@@ -96,7 +113,7 @@ def classes_for_action_type(action_type):
 
 
 class ActionsSearchForm(Form):
-    """The form for a simple search"""
+    """Form used to do an advanced search through the logs."""
     u = forms.ModelChoiceField(
         label=_("Performed by"),
         queryset=users.models.User.objects.all(),
@@ -123,7 +140,7 @@ class ActionsSearchForm(Form):
 
 
 class MachineHistorySearchForm(Form):
-    """The form for a simple search"""
+    """Form used to do a search through the machine histories."""
     q = forms.CharField(
         label=_("Search"),
         max_length=100,

logs/models.py

@@ -69,12 +69,16 @@ def make_version_filter(key, value):
 
 class MachineHistorySearchEvent:
     def __init__(self, user, machine, interface, start=None, end=None):
-        """
+        """Initialise an instance of MachineHistorySearchEvent.
-        :param user: User, The user owning the maching at the time of the event
+
-        :param machine: Version, the machine version related to the interface
+        Args:
-        :param interface: Version, the interface targeted by this event
+            user: User, the user owning the machine at the time of the event.
-        :param start: datetime, the date at which this version was created
+            machine: Version, the machine version related to the interface.
-        :param end: datetime, the date at which this version was replace by a new one
+            interface: Version, the interface targeted by this event.
+            start: datetime, the date at which this version was created
+                (default: None).
+            end: datetime, the date at which this version was replace by a new
+                one (default: None).
         """
         self.user = user
         self.machine = machine
@@ -86,9 +90,13 @@ class MachineHistorySearchEvent:
         self.comment = interface.revision.get_comment() or None
 
     def is_similar(self, elt2):
-        """
+        """Check whether two events are similar enough to be merged.
-        Checks whether two events are similar enough to be merged
+
-        :return: bool
+        Args:
+            elt2: MachineHistorySearchEvent, the event to compare with self.
+
+        Returns:
+            A boolean, True if the events can be merged and False otherwise.
         """
         return (
             elt2 is not None
@@ -115,10 +123,14 @@ class MachineHistorySearch:
         self._last_evt = None
 
     def get(self, search, params):
-        """
+        """Get the events in machine histories related to the search.
-        :param search: ip or mac to lookup
+
-        :param params: dict built by the search view
+        Args:
-        :return: list or None, a list of MachineHistorySearchEvent in reverse chronological order
+            search: the IP or MAC address used in the search.
+            params: the dictionary built by the search view.
+
+        Returns:
+            A list of MachineHistorySearchEvent in reverse chronological order.
         """
         self.start = params.get("s", None)
         self.end = params.get("e", None)
@@ -140,11 +152,12 @@ class MachineHistorySearch:
         return []
 
     def _add_revision(self, user, machine, interface):
-        """
+        """Add a new revision to the chronological order.
-        Add a new revision to the chronological order
+
-        :param user: User, The user owning the maching at the time of the event
+        Args:
-        :param machine: Version, the machine version related to the interface
+            user: User, the user owning the maching at the time of the event.
-        :param interface: Version, the interface targeted by this event
+            machine: Version, the machine version related to the interface.
+            interface: Version, the interface targeted by this event.
         """
         evt = MachineHistorySearchEvent(user, machine, interface)
         evt.start_date = interface.revision.date_created
@@ -171,10 +184,15 @@ class MachineHistorySearch:
         self._last_evt = evt
 
     def _get_interfaces_for_ip(self, ip):
-        """
+        """Get the Version objects of interfaces with the given IP
-        :param ip: str
+        address.
-        :return: An iterable object with the Version objects
+
-                 of Interfaces with the given IP
+        Args:
+            ip: the string corresponding to the IP address.
+
+        Returns:
+            An iterable object with the Version objects of interfaces with the
+            given IP address.
         """
         # TODO: What if ip list was deleted?
         try:
@@ -189,10 +207,15 @@ class MachineHistorySearch:
         )
 
     def _get_interfaces_for_mac(self, mac):
-        """
+        """Get the Version objects of interfaces with the given MAC
-        :param mac: str
+        address.
-        :return: An iterable object with the Version objects
+
-                 of Interfaces with the given MAC address
+        Args:
+            mac: the string corresponding to the MAC address.
+
+        Returns:
+            An iterable object with the Version objects of interfaces with the
+            given MAC address.
         """
         return (
             Version.objects.get_for_model(Interface)
@@ -201,10 +224,14 @@ class MachineHistorySearch:
         )
 
     def _get_machines_for_interface(self, interface):
-        """
+        """Get the Version objects of machines with the given interface.
-        :param interface: Version, the interface for which to find the machines
+
-        :return: An iterable object with the Version objects of Machine to
+        Args:
-                 which the given interface was attributed
+            interface: Version, the interface used to find machines.
+
+        Returns:
+            An iterable object with the Version objects of machines to which
+            the given interface was assigned.
         """
         machine_id = interface.field_dict["machine_id"]
         return (
@@ -214,18 +241,27 @@ class MachineHistorySearch:
         )
 
     def _get_user_for_machine(self, machine):
-        """
+        """Get the User instance owning the given machine.
-        :param machine: Version, the machine of which the owner must be found
+
-        :return: The user to which the given machine belongs
+        Args:
+            machine: Version, the machine used to find its owner.
+
+        Returns:
+            The User instance of the owner of the given machine.
         """
         # TODO: What if user was deleted?
         user_id = machine.field_dict["user_id"]
         return User.objects.get(id=user_id)
 
     def _get_by_ip(self, ip):
-        """
+        """Get events related to the given IP address.
-        :param ip: str, The IP to lookup
+
-        :returns: list, a list of MachineHistorySearchEvent
+        Args:
+            ip: the string corresponding to the IP address.
+
+        Returns:
+            A list of MachineHistorySearchEvent related to the given IP
+            address.
         """
         interfaces = self._get_interfaces_for_ip(ip)
 
@@ -239,9 +275,14 @@ class MachineHistorySearch:
         return self.events
 
     def _get_by_mac(self, mac):
-        """
+        """Get events related to the given MAC address.
-        :param mac: str, The MAC address to lookup
+
-        :returns: list, a list of MachineHistorySearchEvent
+        Args:
+            mac: the string corresponding to the MAC address.
+
+        Returns:
+            A list of MachineHistorySearchEvent related to the given MAC
+            address.
         """
         interfaces = self._get_interfaces_for_mac(mac)
 
@@ -261,10 +302,10 @@ class MachineHistorySearch:
 
 class RelatedHistory:
     def __init__(self, version):
-        """
+        """Initialise an instance of RelatedHistory.
-        :param name: Name of this instance
+
-        :param model_name: Name of the related model (e.g. "user")
+        Args:
-        :param object_id: ID of the related object
+            version: Version, the version related to the history.
         """
         self.version = version
         self.app_name = version.content_type.app_label
@@ -287,10 +328,14 @@ class RelatedHistory:
 
 class HistoryEvent:
     def __init__(self, version, previous_version=None, edited_fields=None):
-        """
+        """Initialise an instance of HistoryEvent.
-        :param version: Version, the version of the object for this event
+
-        :param previous_version: Version, the version of the object before this event
+        Args:
-        :param edited_fields: list, The list of modified fields by this event
+            version: Version, the version of the object for this event.
+            previous_version: Version, the version of the object before this
+                event (default: None).
+            edited_fields: list, The list of modified fields by this event
+                (default: None).
         """
         self.version = version
         self.previous_version = previous_version
@@ -300,11 +345,15 @@ class HistoryEvent:
         self.comment = version.revision.get_comment() or None
 
     def _repr(self, name, value):
-        """
+        """Get the appropriate representation of the given field.
-        Returns the best representation of the given field
+
-        :param name: the name of the field
+        Args:
-        :param value: the value of the field
+            name: the name of the field
-        :return: object
+            value: the value of the field
+
+        Returns:
+            The string corresponding to the appropriate representation of the
+            given field.
         """
         if value is None:
             return _("None")
@@ -312,10 +361,14 @@ class HistoryEvent:
         return value
 
     def edits(self, hide=[]):
-        """
+        """Get the list of the changes performed during this event.
-        Build a list of the changes performed during this event
+
-        :param hide: list, the list of fields for which not to show details
+        Args:
-        :return: str
+            hide: the list of fields for which not to show details (default:
+            []).
+
+        Returns:
+            The list of fields edited by the event to display.
         """
         edits = []
 
@@ -342,10 +395,15 @@ class History:
         self.event_type = HistoryEvent
 
     def get(self, instance_id, model):
-        """
+        """Get the list of history events of the given object.
-        :param instance_id: int, The id of the instance to lookup
+
-        :param model: class, The type of object to lookup
+        Args:
-        :return: list or None, a list of HistoryEvent, in reverse chronological order
+            instance_id: int, the id of the instance to lookup.
+            model: class, the type of object to lookup.
+
+        Returns:
+            A list of HistoryEvent, in reverse chronological order, related to
+            the given object or None if no version was found.
         """
         self.events = []
 
@@ -368,12 +426,16 @@ class History:
         return self.events[::-1]
 
     def _compute_diff(self, v1, v2, ignoring=[]):
-        """
+        """Find the edited fields between two versions.
-        Find the edited field between two versions
+
-        :param v1: Version
+        Args:
-        :param v2: Version
+            v1: Version to compare.
-        :param ignoring: List, a list of fields to ignore
+            v2: Version to compare.
-        :return: List of field names
+            ignoring: a list of fields to ignore.
+
+        Returns:
+            The list of field names in v1 that are different from the ones in
+            v2.
         """
         fields = []
 
@@ -384,9 +446,10 @@ class History:
         return fields
 
     def _add_revision(self, version):
-        """
+        """Add a new revision to the chronological order.
-        Add a new revision to the chronological order
+
-        :param version: Version, The version of the interface for this event
+        Args:
+            version: Version, the version of the interface for this event.
         """
         diff = None
         if self._last_version is not None:
@@ -427,6 +490,15 @@ class VersionAction(HistoryEvent):
         return apps.get_model(self.application(), self.model_name())
 
     def edits(self, hide=["password", "pwd_ntlm", "gpg_fingerprint"]):
+        """Get the list of the changes performed during this event.
+
+        Args:
+            hide: the list of fields for which not to show details (default:
+            ["password", "pwd_ntlm", "gpg_fingerprint"]).
+
+        Returns:
+            The list of fields edited by the event to display.
+        """
         self.previous_version = self._previous_version()
 
         if self.previous_version is None:
@@ -436,6 +508,12 @@ class VersionAction(HistoryEvent):
         return super(VersionAction, self).edits(hide)
 
     def _previous_version(self):
+        """Get the previous version of self.
+
+        Returns:
+            The Version corresponding to the previous version of self, or None
+            in case of exception.
+        """
         model = self.object_type()
         try:
             query = (
@@ -451,12 +529,16 @@ class VersionAction(HistoryEvent):
             return None
 
     def _compute_diff(self, v1, v2, ignoring=["pwd_ntlm"]):
-        """
+        """Find the edited fields between two versions.
-        Find the edited field between two versions
+
-        :param v1: Version
+        Args:
-        :param v2: Version
+            v1: Version to compare.
-        :param ignoring: List, a list of fields to ignore
+            v2: Version to compare.
-        :return: List of field names
+            ignoring: a list of fields to ignore (default: ["pwd_ntlm"]).
+
+        Returns:
+            The list of field names in v1 that are different from the ones in
+            v2.
         """
         fields = []
 
@@ -468,7 +550,8 @@ class VersionAction(HistoryEvent):
 
 
 class RevisionAction:
-    """A Revision may group multiple Version objects together"""
+    """A Revision may group multiple Version objects together."""
+
     def __init__(self, revision):
         self.performed_by = revision.user
         self.revision = revision
@@ -486,9 +569,13 @@ class RevisionAction:
 
 class ActionsSearch:
     def get(self, params):
-        """
+        """Get the Revision objects corresponding to the search.
-        :param params: dict built by the search view
+
-        :return: QuerySet of Revision objects
+        Args:
+            params: dictionary built by the search view.
+
+        Returns:
+            The QuerySet of Revision objects corresponding to the search.
         """
         user = params.get("u", None)
         start = params.get("s", None)
@@ -540,11 +627,15 @@ class ActionsSearch:
 
 class UserHistoryEvent(HistoryEvent):
     def _repr(self, name, value):
-        """
+        """Get the appropriate representation of the given field.
-        Returns the best representation of the given field
+
-        :param name: the name of the field
+        Args:
-        :param value: the value of the field
+            name: the name of the field
-        :return: object
+            value: the value of the field
+
+        Returns:
+            The string corresponding to the appropriate representation of the
+            given field.
         """
         if name == "groups":
             if len(value) == 0:
@@ -599,10 +690,14 @@ class UserHistoryEvent(HistoryEvent):
         return super(UserHistoryEvent, self)._repr(name, value)
 
     def edits(self, hide=["password", "pwd_ntlm", "gpg_fingerprint"]):
-        """
+        """Get the list of the changes performed during this event.
-        Build a list of the changes performed during this event
+
-        :param hide: list, the list of fields for which not to show details
+        Args:
-        :return: str
+            hide: the list of fields for which not to show details (default:
+            ["password", "pwd_ntlm", "gpg_fingerprint"]).
+
+        Returns:
+            The list of fields edited by the event to display.
         """
         return super(UserHistoryEvent, self).edits(hide)
 
@@ -631,9 +726,14 @@ class UserHistory(History):
         self.event_type = UserHistoryEvent
 
     def get(self, user_id, model):
-        """
+        """Get the the list of UserHistoryEvent related to the object.
-        :param user_id: int, the id of the user to lookup
+
-        :return: list or None, a list of UserHistoryEvent, in reverse chronological order
+        Args:
+            user_id: int, the id of the user to lookup.
+
+        Returns:
+            The list of UserHistoryEvent, in reverse chronological order,
+            related to the object, or None if nothing was found.
         """
         self.events = []
 
@@ -710,10 +810,10 @@ class UserHistory(History):
         )
 
     def _add_revision(self, version):
-        """
+        """Add a new revision to the chronological order.
-        Add a new revision to the chronological order
+
-        :param user: User, The user displayed in this history
+        Args:
-        :param version: Version, The version of the user for this event
+            version: Version, the version of the user for this event.
         """
         diff = None
         if self._last_version is not None:
@@ -736,11 +836,15 @@ class UserHistory(History):
 
 class MachineHistoryEvent(HistoryEvent):
     def _repr(self, name, value):
-        """
+        """Return the appropriate representation of the given field.
-        Returns the best representation of the given field
+
-        :param name: the name of the field
+        Args:
-        :param value: the value of the field
+            name: the name of the field
-        :return: object
+            value: the value of the field
+
+        Returns:
+            The string corresponding to the appropriate representation of the
+            given field.
         """
         if name == "user_id":
             try:
@@ -757,6 +861,15 @@ class MachineHistory(History):
         self.event_type = MachineHistoryEvent
 
     def get(self, machine_id, model):
+        """Get the the list of MachineHistoryEvent related to the object.
+
+        Args:
+            machine_id: int, the id of the machine to lookup.
+
+        Returns:
+            The list of MachineHistoryEvent, in reverse chronological order,
+            related to the object.
+        """
         self.related = (
             Version.objects.get_for_model(Interface)
             .filter(make_version_filter("machine", machine_id))
@@ -772,11 +885,15 @@ class MachineHistory(History):
 
 class InterfaceHistoryEvent(HistoryEvent):
     def _repr(self, name, value):
-        """
+        """Get the appropriate representation of the given field.
-        Returns the best representation of the given field
+
-        :param name: the name of the field
+        Args:
-        :param value: the value of the field
+            name: the name of the field
-        :return: object
+            value: the value of the field
+
+        Returns:
+            The string corresponding to the appropriate representation of the
+            given field.
         """
         if name == "ipv4_id" and value is not None:
             try:
@@ -813,6 +930,15 @@ class InterfaceHistory(History):
         self.event_type = InterfaceHistoryEvent
 
     def get(self, interface_id, model):
+        """Get the the list of InterfaceHistoryEvent related to the object.
+
+        Args:
+            interface_id: int, the id of the interface to lookup.
+
+        Returns:
+            The list of InterfaceHistoryEvent, in reverse chronological order,
+            related to the object.
+        """
         return super(InterfaceHistory, self).get(interface_id, Interface)
 
 
@@ -829,10 +955,15 @@ HISTORY_CLASS_MAPPING = {
 
 
 def get_history_class(model):
-    """
+    """Get the most appropriate History subclass to represent the given model's
-    Find the mos appropriate History subclass to represent
+    history.
-    the given model's history
+
-    :model: class
+    Args:
+        model: the class for which to get the history.
+
+    Returns:
+        The most appropriate History subclass for the given model's history,
+        or History if no other was found.
     """
     try:
         return HISTORY_CLASS_MAPPING[model]()

logs/views.py

@@ -113,8 +113,7 @@ from .forms import ActionsSearchForm, MachineHistorySearchForm
 @login_required
 @can_view_app("logs")
 def index(request):
-    """Affiche les logs affinés, date reformatées, selectionne
+    """View used to display summary of events about users."""
-    les event importants (ajout de droits, ajout de ban/whitelist)"""
     pagination_number = GeneralOption.get_cached_value("pagination_number")
     # The types of content kept for display
     content_type_filter = ["ban", "whitelist", "vente", "interface", "user"]
@@ -155,8 +154,7 @@ def index(request):
 @login_required
 @can_view_all(GeneralOption)
 def stats_logs(request):
-    """Affiche l'ensemble des logs et des modifications sur les objets,
+    """View used to do an advanced search through the logs."""
-    classés par date croissante, en vrac"""
     actions_form = ActionsSearchForm(request.GET or None)
 
     if actions_form.is_valid():
@@ -185,7 +183,7 @@ def stats_logs(request):
 @login_required
 @can_edit_history
 def revert_action(request, revision_id):
-    """ Annule l'action en question """
+    """View used to revert actions."""
     try:
         revision = Revision.objects.get(id=revision_id)
     except Revision.DoesNotExist:
@@ -204,9 +202,10 @@ def revert_action(request, revision_id):
 @login_required
 @can_view_all(IpList, Interface, User)
 def stats_general(request):
-    """Statistiques générales affinées sur les ip, activées, utilisées par
+    """View used to display general statistics about users (activated,
-    range, et les statistiques générales sur les users : users actifs,
+    disabled, archived etc.) and IP addresses (ranges, number of assigned
-    cotisants, activés, archivés, etc"""
+    addresses etc.).
+    """
     ip_dict = dict()
     for ip_range in IpType.objects.select_related("vlan").all():
         all_ip = IpList.objects.filter(ip_type=ip_range)
@@ -377,9 +376,9 @@ def stats_general(request):
 @login_required
 @can_view_app("users", "cotisations", "machines", "topologie")
 def stats_models(request):
-    """Statistiques générales, affiche les comptages par models:
+    """View used to display general statistics about the number of objects
-    nombre d'users, d'écoles, de droits, de bannissements,
+    stored in the database, for each model.
-    de factures, de ventes, de banque, de machines, etc"""
+    """
     stats = {
         _("Users (members and clubs)"): {
             "users": [User._meta.verbose_name, User.objects.count()],
@@ -452,10 +451,9 @@ def stats_models(request):
 @login_required
 @can_view_app("users")
 def stats_users(request):
-    """Affiche les statistiques base de données aggrégées par user :
+    """View used to display statistics aggregated by user (number of machines,
-    nombre de machines par user, d'etablissements par user,
+    bans, whitelists, rights etc.).
-    de moyens de paiements par user, de banque par user,
+    """
-    de bannissement par user, etc"""
     stats = {
         User._meta.verbose_name: {
             Machine._meta.verbose_name_plural: User.objects.annotate(
@@ -496,9 +494,7 @@ def stats_users(request):
 @login_required
 @can_view_app("users")
 def stats_actions(request):
-    """Vue qui affiche les statistiques de modifications d'objets par
+    """View used to display the number of actions, aggregated by user."""
-    utilisateurs.
-    Affiche le nombre de modifications aggrégées par utilisateurs"""
     stats = {
         User._meta.verbose_name: {
             _("actions"): User.objects.annotate(num=Count("revision")).order_by("-num")[
@@ -512,8 +508,9 @@ def stats_actions(request):
 @login_required
 @can_view_app("users")
 def stats_search_machine_history(request):
-    """View which displays the history of machines with the given
+    """View used to display the history of machines with the given IP or MAC
-    une IP or MAC adresse"""
+    address.
+    """
     history_form = MachineHistorySearchForm(request.GET or None)
     if history_form.is_valid():
         history = MachineHistorySearch()