Hide keyboard shortcuts

Hot-keys on this page

r m x p   toggle line displays

j k   next/prev highlighted chunk

0   (zero) top of page

1   (one) first highlighted chunk

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

60

61

62

63

64

65

66

67

68

69

70

71

72

# Copyright (C) 2015 Chintalagiri Shashank 

# 

# This file is part of Tendril. 

# 

# This program is free software: you can redistribute it and/or modify 

# it under the terms of the GNU Affero General Public License as published by 

# the Free Software Foundation, either version 3 of the License, or 

# (at your option) any later version. 

# 

# This program is distributed in the hope that it will be useful, 

# but WITHOUT ANY WARRANTY; without even the implied warranty of 

# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 

# GNU Affero General Public License for more details. 

# 

# You should have received a copy of the GNU Affero General Public License 

# along with this program.  If not, see <http://www.gnu.org/licenses/>. 

""" 

The Utils Package (:mod:`tendril.utils`) 

======================================== 

 

The :mod:`utils` package contains various Utils modules which provide 

functionality that is either : 

 

- Logically independent of the main Tendril functionality. 

- Used by multiple Tendril's packages, either due to generic nature of the 

  functionality, or because it defines the structure that functionality should 

  take within Tendril. 

 

These modules typically expose specific functionality of third-party or 

built-in Python modules and simplify access by restricting the ways in which 

these modules can be used. For instance, various options are preselected 

within the Utils module, meaning application code does not have to bother 

about it. This comes at the cost of reducing the flexibility available when 

using this functionality in application code. 

 

The intent of the :mod:`tendril.utils` package and it's modules is to attempt 

to create a consistent structure throughout the :mod:`tendril` codebase. The 

:mod:`tendril.utils` module, in effect, specifies the preferred way to do 

certain common things. Tendril application code which makes use of the 

functionality of this module is expected to benefit in the form of 

consistency, relative ease in honoring user-provided parameters (across the 

codebase), and not need to deal with the underlying libraries and the wide 

range of usage options available for the most common cases. 

 

It is expected that this structure will be critical to being able to easily 

adapt the Tendril codebase to new environments and for making more flexibility 

accessible to administrators of Tendril instances. 

 

Many of the modules provided here can be re-implemented to use different 

underlying implementations, while preserving the interface they present to 

Tendril application code. 

 

.. warning:: It is possible that this approach will soon reach the point of 

             diminishing returns. 

 

.. rubric:: The Utility Modules 

 

.. toctree:: 

 

    tendril.utils.terminal 

    tendril.utils.types 

    tendril.utils.colors 

    tendril.utils.config 

    tendril.utils.db 

    tendril.utils.fsutils 

    tendril.utils.libreoffice 

    tendril.utils.log 

    tendril.utils.pdf 

    tendril.utils.vcs 

    tendril.utils.www 

 

"""