1# -*- coding: utf-8 -*-
2"""
3obspy.io.xseed - (X)SEED and RESP support for ObsPy
4===================================================
5`XML-SEED` was introduced by Tsuboi, Tromp and Komatitsch (2004), it is a XML
6representation of `Dataless SEED`. This module contains converters from
7`Dataless SEED` to `XML-SEED` and vice versa as well as a converter from
8`Dataless SEED` to `RESP` files. The :mod:`~obspy.io.xseed` module is tested
9against the complete ORFEUS Dataless SEED archive, the IRIS (US) Dataless SEED
10archive and against ArcLink response requests.
11
12All files can be converted to ObsPy's internal inventory objects at which
13point they can be written out to any format ObsPy supports. In the case of
14RESP files these are potentially incomplete as RESP files lack vital
15information like geographical coordinates.
16
17:copyright:
18    The ObsPy Development Team (devs@obspy.org)
19:license:
20    GNU Lesser General Public License, Version 3
21    (https://www.gnu.org/copyleft/lesser.html)
22
23Allocate a Parser object and read/write
24---------------------------------------
25
26>>> from obspy.io.xseed import Parser
27>>> sp = Parser("/path/to/dataless.seed.BW_FURT")
28>>> sp.write_xseed("dataless.seed.BW_RJOB.xml") #doctest: +SKIP
29
30The lines above will convert `Dataless SEED`, e.g.::
31
32    000001V 010009402.3121970,001,00:00:00.0000~2038,001,00:00:00.0000~
33    2009,037,04:32:41.0000~BayernNetz~~0110032002RJOB 000003RJOB 000008
34    ...
35
36to the `XML-SEED` representation, e.g.::
37
38    <?xml version='1.0' encoding='utf-8'?>
39    <xseed version="1.0">
40      <volume_index_control_header>
41        <volume_identifier blockette="010">
42          <version_of_format>2.4</version_of_format>
43          <logical_record_length>12</logical_record_length>
44          <beginning_time>1970-01-01T00:00:00</beginning_time>
45          <end_time>2038-01-01T00:00:00</end_time>
46          <volume_time>2009-02-06T04:32:41</volume_time>
47          <originating_organization>BayernNetz</originating_organization>
48    ...
49
50
51A response file can be written in a similar manner, just replace
52:meth:`~obspy.io.xseed.parser.Parser.write_xseed` by
53:meth:`~obspy.io.xseed.parser.Parser.write_resp`:
54
55>>> sp.write_resp(folder="BW_FURT", zipped=False) #doctest: +SKIP
56
57
58The Parser Object
59-----------------
60
61`SEED` files as well as its derived format `XML-SEED` will be
62parsed in a :class:`~obspy.io.xseed.parser.Parser` structure.
63
64`SEED` volumes have four different volume types:
65
66* Volume Index Control Headers
67* Abbreviation Dictionary Control Headers
68* Station Control Headers
69* Time Span Control Headers (currently not supported by ObsPy. Some dummy
70  headers will be written in case they are needed by SEED/XSEED conventions.)
71
72After parsing a `SEED` or `XML-SEED` file the Blockette objects for each
73volume will be stored in the attributes``Parser.volume``,
74``Parser.abbreviations`` and ``Parser.stations``. Each item is a list of all
75related Blockettes and ``Parser.stations`` is a list of stations which contains
76all related Blockettes.
77"""
78from __future__ import (absolute_import, division, print_function,
79                        unicode_literals)
80from future.builtins import *  # NOQA
81
82# needs to stay above import statements
83DEFAULT_XSEED_VERSION = '1.1'
84
85
86class InvalidResponseError(Exception):
87    """
88    Raised when a response is clearly invalid.
89
90    The error message should give a clearer idea of why.
91    """
92    pass
93
94
95from .parser import Parser
96
97
98if __name__ == '__main__':
99    import doctest
100    doctest.testmod(exclude_empty=True)
101