Skip to content

Commit fde42f2

Browse files
authored
fix #409 : added documentation for Workbook class
1 parent e67ddea commit fde42f2

3 files changed

Lines changed: 99 additions & 9 deletions

File tree

‎doc/source/api.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -494,6 +494,14 @@ Excel
494494

495495
open_excel
496496

497+
.. autosummary::
498+
:toctree: _generated/
499+
500+
Workbook
501+
Workbook.sheet_names
502+
Workbook.save
503+
Workbook.close
504+
497505
.. _api-misc:
498506

499507
Miscellaneous

‎larray/inout/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
from __future__ import absolute_import, division, print_function
22

3-
from larray.inout.excel import open_excel
3+
from larray.inout.excel import *
44
from larray.inout.array import *
55
from larray.inout.session import *

‎larray/inout/excel.py‎

Lines changed: 90 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
# -*- coding: utf8 -*-
2+
from __future__ import absolute_import, print_function
3+
4+
__all__ = ['open_excel', 'Workbook']
5+
6+
17
import os
28
import atexit
39

@@ -9,8 +15,9 @@
915

1016
from larray.core.group import _translate_sheet_name
1117
from larray.core.axis import Axis
12-
from larray.core.array import LArray
18+
from larray.core.array import LArray, ndtest
1319
from larray.inout.array import df_aslarray, from_lists
20+
from larray.util.misc import PY2
1421

1522
string_types = (str,)
1623

@@ -59,7 +66,6 @@ def write_value(cls, value, options):
5966
# TODO: replace overwrite_file by mode='r'|'w'|'a' the day xlwings will support a read-only mode
6067
class Workbook(object):
6168
def __init__(self, filepath=None, overwrite_file=False, visible=None, silent=None, app=None):
62-
"""See open_excel doc for parameters"""
6369
global global_app
6470

6571
xw_wkb = None
@@ -226,10 +232,8 @@ def save(self, path=None):
226232
self.xw_wkb.save(path=path)
227233

228234
def close(self):
229-
"""
230-
Close the workbook in Excel. This will not quit the Excel instance, even if this was the last workbook of
231-
that Excel instance.
232-
"""
235+
# Close the workbook in Excel.
236+
# This will not quit the Excel instance, even if this was the last workbook of that Excel instance.
233237
if self.filepath is not None and os.path.isfile(self.xw_wkb.fullname):
234238
tmp_file = self.xw_wkb.fullname
235239
self.xw_wkb.close()
@@ -555,13 +559,92 @@ def load(self, header=True, convert_float=True, nb_index=None, index_col=None, f
555559
else:
556560
return LArray(list_data)
557561

558-
# XXX: remove this function?
562+
# XXX: deprecate this function?
559563
def open_excel(filepath=None, overwrite_file=False, visible=None, silent=None, app=None):
560564
return Workbook(filepath, overwrite_file, visible, silent, app)
561565
else:
566+
class Workbook(object):
567+
def __init__(self, filepath=None, overwrite_file=False, visible=None, silent=None, app=None):
568+
raise Exception("Workbook class cannot be instanciated because xlwings is not installed")
569+
570+
def sheet_names(self):
571+
raise Exception()
572+
573+
def save(self, path=None):
574+
raise Exception()
575+
576+
def close(self):
577+
raise Exception()
578+
562579
def open_excel(filepath=None, overwrite_file=False, visible=None, silent=None, app=None):
563580
raise Exception("open_excel() is not available because xlwings is not installed")
564581

582+
583+
# We define Workbook and open_excel documentation here since Readthedocs runs on Linux
584+
if not PY2:
585+
Workbook.__doc__ = """
586+
Excel Workbook.
587+
588+
See Also
589+
--------
590+
open_excel
591+
"""
592+
593+
Workbook.sheet_names.__doc__ = """
594+
Returns the names of the Excel sheets.
595+
596+
Examples
597+
--------
598+
>>> arr, arr2, arr3 = ndtest((3, 3)), ndtest((2, 2)), ndtest(4)
599+
>>> with open_excel('excel_file.xlsx', overwrite_file=True) as wb: # doctest: +SKIP
600+
... wb['arr'] = arr.dump()
601+
... wb['arr2'] = arr2.dump()
602+
... wb['arr3'] = arr3.dump()
603+
... wb.save()
604+
...
605+
... wb.sheet_names()
606+
['arr', 'arr2', 'arr3']
607+
"""
608+
609+
Workbook.save.__doc__ = """
610+
Saves the Workbook.
611+
612+
If a path is being provided, this works like SaveAs() in Excel.
613+
If no path is specified and if the file hasn’t been saved previously,
614+
it’s being saved in the current working directory with the current filename.
615+
Existing files are overwritten without prompting.
616+
617+
Parameters
618+
----------
619+
path : str, optional
620+
Full path to the workbook. Defaults to None.
621+
622+
Examples
623+
--------
624+
>>> arr, arr2, arr3 = ndtest((3, 3)), ndtest((2, 2)), ndtest(4)
625+
>>> with open_excel('excel_file.xlsx', overwrite_file=True) as wb: # doctest: +SKIP
626+
... wb['arr'] = arr.dump()
627+
... wb['arr2'] = arr2.dump()
628+
... wb['arr3'] = arr3.dump()
629+
... wb.save()
630+
"""
631+
632+
Workbook.close.__doc__ = """
633+
Close the workbook in Excel.
634+
635+
Need to be called if the workbook has been opened without the `with` statement.
636+
637+
Examples
638+
--------
639+
>>> arr, arr2, arr3 = ndtest((3, 3)), ndtest((2, 2)), ndtest(4) # doctest: +SKIP
640+
>>> wb = open_excel('excel_file.xlsx', overwrite_file=True) # doctest: +SKIP
641+
>>> wb['arr'] = arr.dump() # doctest: +SKIP
642+
>>> wb['arr2'] = arr2.dump() # doctest: +SKIP
643+
>>> wb['arr3'] = arr3.dump() # doctest: +SKIP
644+
>>> wb.save() # doctest: +SKIP
645+
>>> wb.close() # doctest: +SKIP
646+
"""
647+
565648
open_excel.__doc__ = """
566649
Open an Excel workbook
567650
@@ -592,7 +675,6 @@ def open_excel(filepath=None, overwrite_file=False, visible=None, silent=None, a
592675
593676
Examples
594677
--------
595-
>>> from larray import *
596678
>>> arr = ndtest((3, 3))
597679
>>> arr
598680
a\\b b0 b1 b2

0 commit comments

Comments
 (0)