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
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
**************
Logging system
**************
.. note::
The Astropy logging system is meant for internal ``astropy`` usage. For use
in other packages, we recommend implementing your own logger instead.
Overview
========
The Astropy logging system is designed to give users flexibility in deciding
which log messages to show, to capture them, and to send them to a file.
All messages printed by Astropy routines should use the built-in logging
facility (normal ``print()`` calls should only be done by routines that are
explicitly requested to print output). Messages can have one of several
levels:
* DEBUG: Detailed information, typically of interest only when diagnosing
problems.
* INFO: An message conveying information about the current task, and
confirming that things are working as expected
* WARNING: An indication that something unexpected happened, and that user
action may be required.
* ERROR: indicates a more serious issue, including exceptions
By default, INFO, WARNING and ERROR messages are displayed, and are sent to a
log file located at ``~/.astropy/astropy.log`` (if the file is writeable).
Configuring the logging system
==============================
First, import the logger::
from astropy import log
The threshold level (defined above) for messages can be set with e.g.::
log.setLevel('DEBUG')
Color (enabled by default) can be disabled with::
log.disable_color()
and enabled with::
log.enable_color()
Warnings from ``warnings.warn`` can be logged with::
log.enable_warnings_logging()
which can be disabled with::
log.disable_warnings_logging()
and exceptions can be included in the log with::
log.enable_exception_logging()
which can be disabled with::
log.disable_exception_logging()
It is also possible to set these settings from the Astropy configuration file,
which also allows an overall log file to be specified. See
`Using the configuration file`_ for more information.
Context managers
================
In some cases, you may want to capture the log messages, for example to check
whether a specific message was output, or to log the messages from a specific
section of code to a file. Both of these are possible using context managers.
To add the log messages to a list, first import the logger if you have not
already done so::
from astropy import log
then enclose the code in which you want to log the messages to a list in a
``with`` statement::
with log.log_to_list() as log_list:
# your code here
In the above example, once the block of code has executed, ``log_list`` will
be a Python list containing all the Astropy logging messages that were raised.
Note that messages continue to be output as normal.
Similarly, you can output the log messages of a specific section of code to a
file using::
with log.log_to_file('myfile.log'):
# your code here
which will add all the messages to ``myfile.log`` (this is in addition to the
overall log file mentioned in `Using the configuration file`_).
While these context managers will include all the messages emitted by the
logger (using the global level set by ``log.setLevel``), it is possible to
filter a subset of these using ``filter_level=``, and specifying one of
``'DEBUG'``, ``'INFO'``, ``'WARN'``, ``'ERROR'``. Note that if
``filter_level`` is a lower level than that set via ``setLevel``, only
messages with the level set by ``setLevel`` or higher will be included (i.e.
``filter_level`` is only filtering a subset of the messages normally emitted
by the logger).
Similarly, it is possible to filter a subset of the messages by origin by
specifying ``filter_origin=`` followed by a string. If the origin of a message
starts with that string, the message will be included in the context manager.
For example, ``filter_origin='astropy.wcs'`` will include only messages
emitted in the ``astropy.wcs`` sub-package.
Using the configuration file
============================
Options for the logger can be set in the ``[logger]`` section
of the Astropy configuration file::
[logger]
# Threshold for the logging messages. Logging messages that are less severe
# than this level will be ignored. The levels are 'DEBUG', 'INFO', 'WARNING',
# 'ERROR'
log_level = 'INFO'
# Whether to use color for the level names
use_color = True
# Whether to log warnings.warn calls
log_warnings = False
# Whether to log exceptions before raising them
log_exceptions = False
# Whether to always log messages to a log file
log_to_file = True
# The file to log messages to. If empty string is given, it defaults to a
# file `astropy.log` in the astropy config directory.
log_file_path = '~/.astropy/astropy.log'
# Threshold for logging messages to log_file_path
log_file_level = 'INFO'
# Format for log file entries
log_file_format = '%(asctime)s, %(origin)s, %(levelname)s, %(message)s'
# The encoding (e.g., UTF-8) to use for the log file. If empty string is
# given, it defaults to the platform-preferred encoding.
log_file_encoding = ""
Reference/API
=============
.. automodapi:: astropy.logger
:no-inheritance-diagram:
|
