Skip to content

Commit e27878e

Browse files
blattmsblattms
authored
Merge pull request #4405 from lisajulia/feature/pyAction-documentation
Add missing documentation
2 parents 50288c2 + bd81d65 commit e27878e

File tree

6 files changed

+417
-103
lines changed

6 files changed

+417
-103
lines changed

‎python/cxx/connection.cpp‎

Lines changed: 20 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
#include "export.hpp"
44

5+
#include <python/cxx/OpmCommonPythonDoc.hpp>
6+
57
namespace {
68

79
std::string state( const Connection& c ) {
@@ -21,20 +23,22 @@ std::tuple<int, int, int> get_pos( const Connection& conn ) {
2123

2224
void python::common::export_Connection(py::module& module) {
2325

24-
py::class_< Connection >( module, "Connection")
25-
.def_property_readonly("direction", &direction )
26-
.def_property_readonly("state", &state )
27-
.def_property_readonly( "i", &Connection::getI )
28-
.def_property_readonly( "j", &Connection::getJ )
29-
.def_property_readonly( "k", &Connection::getK )
30-
.def_property_readonly( "pos", &get_pos )
31-
.def_property_readonly( "attached_to_segment", &Connection::attachedToSegment )
32-
.def_property_readonly( "center_depth", &Connection::depth)
33-
.def_property_readonly( "rw", &Connection::rw)
34-
.def_property_readonly( "complnum", &Connection::complnum)
35-
.def_property_readonly( "number", &Connection::complnum) // This is deprecated; complnum is the "correct" proeprty name
36-
.def_property_readonly( "sat_table_id", &Connection::satTableId)
37-
.def_property_readonly( "segment_number", &Connection::segment)
38-
.def_property_readonly( "cf", &Connection::CF)
39-
.def_property_readonly( "kh", &Connection::Kh);
26+
using namespace Opm::Common::DocStrings;
27+
28+
py::class_<Connection>(module, "Connection", Connection_docstring)
29+
.def_property_readonly("direction", &direction, Connection_direction_docstring)
30+
.def_property_readonly("state", &state, Connection_state_docstring)
31+
.def_property_readonly("i", &Connection::getI, Connection_getI_docstring)
32+
.def_property_readonly("j", &Connection::getJ, Connection_getJ_docstring)
33+
.def_property_readonly("k", &Connection::getK, Connection_getK_docstring)
34+
.def_property_readonly("pos", &get_pos, Connection_pos_docstring)
35+
.def_property_readonly("attached_to_segment", &Connection::attachedToSegment, Connection_attachedToSegment_docstring)
36+
.def_property_readonly("center_depth", &Connection::depth, Connection_depth_docstring)
37+
.def_property_readonly("rw", &Connection::rw, Connection_rw_docstring)
38+
.def_property_readonly("complnum", &Connection::complnum, Connection_complnum_docstring)
39+
.def_property_readonly("number", &Connection::complnum, Connection_number_docstring) // DEPRECATED: Use 'complnum' instead.
40+
.def_property_readonly("sat_table_id", &Connection::satTableId, Connection_satTableId_docstring)
41+
.def_property_readonly("segment_number", &Connection::segment, Connection_segment_docstring)
42+
.def_property_readonly("cf", &Connection::CF, Connection_CF_docstring)
43+
.def_property_readonly("kh", &Connection::Kh, Connection_Kh_docstring);
4044
}

‎python/cxx/deck.cpp‎

Lines changed: 21 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
#include "converters.hpp"
66
#include "export.hpp"
77

8+
#include <python/cxx/OpmCommonPythonDoc.hpp>
89

910
namespace {
1011

@@ -45,34 +46,34 @@ namespace {
4546

4647
void python::common::export_Deck(py::module &module) {
4748

49+
using namespace Opm::Common::DocStrings;
50+
4851
// Note: In the below class we use std::shared_ptr as the holder type, see:
4952
//
5053
// https://pybind11.readthedocs.io/en/stable/advanced/smart_ptrs.html
5154
//
5255
// this makes it possible to share the returned object with e.g. and
5356
// opm.simulators.BlackOilSimulator Python object
5457
//
55-
py::class_< Deck, std::shared_ptr<Deck> >(module, "Deck")
56-
.def( "__len__", &size )
57-
.def( "__contains__", &hasKeyword )
58+
py::class_<Deck, std::shared_ptr<Deck>>(module, "Deck", Deck_docstring)
59+
.def("__len__", &size, Deck_len_docstring)
60+
.def("__contains__", &hasKeyword, py::arg("keyword"), Deck_contains_docstring)
5861
.def("__iter__",
59-
[] (const Deck &deck) { return py::make_iterator(deck.begin(), deck.end()); }, py::keep_alive<0, 1>())
60-
.def( "__getitem__", &getKeyword_int, ref_internal)
61-
.def( "__getitem__", &getKeyword_string, ref_internal)
62-
.def( "__getitem__", &getKeyword_tuple, ref_internal)
63-
.def( "__str__", &str<Deck>)
64-
65-
.def("active_unit_system", [](const Deck& deck) -> const UnitSystem& {
66-
return deck.getActiveUnitSystem();
67-
} )
68-
69-
.def("default_unit_system", [](const Deck& deck) -> const UnitSystem& {
70-
return deck.getDefaultUnitSystem();
71-
} )
72-
73-
.def( "count", &count )
74-
.def( "add", &addKeyword)
75-
;
62+
[](const Deck &deck) { return py::make_iterator(deck.begin(), deck.end()); },
63+
py::keep_alive<0, 1>(), Deck_iter_docstring)
64+
.def("__getitem__", &getKeyword_int, py::arg("index"), ref_internal, Deck_getitem_int_docstring)
65+
.def("__getitem__", &getKeyword_string, py::arg("keyword"), ref_internal, Deck_getitem_string_docstring)
66+
.def("__getitem__", &getKeyword_tuple, py::arg("keyword_index"), ref_internal, Deck_getitem_tuple_docstring)
67+
.def("__str__", &str<Deck>, Deck_str_docstring)
68+
.def("active_unit_system",
69+
[](const Deck& deck) -> const UnitSystem& { return deck.getActiveUnitSystem(); },
70+
Deck_active_unit_system_docstring)
71+
.def("default_unit_system",
72+
[](const Deck& deck) -> const UnitSystem& { return deck.getDefaultUnitSystem(); },
73+
Deck_default_unit_system_docstring)
74+
.def("count", &count, py::arg("keyword"), Deck_count_docstring)
75+
.def("add", &addKeyword, py::arg("keyword"), Deck_add_docstring);
76+
7677
}
7778

7879

‎python/cxx/deck_keyword.cpp‎

Lines changed: 42 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,9 @@
1414
#include "export.hpp"
1515
#include "converters.hpp"
1616

17-
#include <iostream>
17+
#include <python/cxx/OpmCommonPythonDoc.hpp>
1818

19+
#include <iostream>
1920

2021
namespace {
2122

@@ -164,11 +165,12 @@ std::string get_string(DeckItem * item, std::size_t index) {
164165

165166
}
166167
void python::common::export_DeckKeyword(py::module& module) {
167-
py::class_< DeckKeyword >( module, "DeckKeyword")
168-
.def(py::init<const ParserKeyword& >())
169168

170-
.def(py::init([](const ParserKeyword& parser_keyword, py::list record_list, UnitSystem& active_system, UnitSystem& default_system) {
169+
using namespace Opm::Common::DocStrings;
171170

171+
py::class_<DeckKeyword>(module, "DeckKeyword", DeckKeyword_docstring)
172+
.def(py::init<const ParserKeyword&>(), py::arg("parser_keyword"), DeckKeyword_init_parser_keyword_docstring)
173+
.def(py::init([](const ParserKeyword& parser_keyword, py::list record_list, UnitSystem& active_system, UnitSystem& default_system) {
172174
std::vector< std::vector<DeckValue> > value_record_list;
173175
int i = 0;
174176
for (py::handle record_obj : record_list) {
@@ -218,27 +220,26 @@ void python::common::export_DeckKeyword(py::module& module) {
218220
value_record_list.push_back( value_record );
219221
}
220222
return DeckKeyword(parser_keyword, value_record_list, active_system, default_system);
221-
} ) )
222-
223-
.def( "__repr__", &DeckKeyword::name )
224-
.def( "__str__", &str<DeckKeyword> )
225-
.def("__iter__", [] (const DeckKeyword &keyword) { return py::make_iterator(keyword.begin(), keyword.end()); }, py::keep_alive<0,1>())
226-
.def( "__getitem__", getRecord, ref_internal)
227-
.def( "__len__", &DeckKeyword::size )
228-
.def_property_readonly("name", &DeckKeyword::name )
229-
230-
.def(py::init([](const ParserKeyword& parser_keyword, py::array_t<int> py_data) {
223+
} ), py::arg("parser_keyword"), py::arg("record_list"), py::arg("active_system"), py::arg("default_system"), DeckKeyword_init_parser_keyword_record_list_docstring)
224+
.def("__repr__", &DeckKeyword::name, DeckKeyword_repr_docstring)
225+
.def("__str__", &str<DeckKeyword>, DeckKeyword_str_docstring)
226+
.def("__iter__", [](const DeckKeyword &keyword) { return py::make_iterator(keyword.begin(), keyword.end()); },
227+
py::keep_alive<0,1>(), DeckKeyword_iter_docstring)
228+
.def("__getitem__", getRecord, ref_internal, py::arg("index"), DeckKeyword_getitem_docstring)
229+
.def("__len__", &DeckKeyword::size, DeckKeyword_len_docstring)
230+
.def_property_readonly("name", &DeckKeyword::name, DeckKeyword_name_docstring)
231+
232+
.def(py::init([](const ParserKeyword& parser_keyword, py::array_t<int> py_data) {
231233
return DeckKeyword(parser_keyword, convert::vector(py_data));
232-
} ) )
234+
}), py::arg("parser_keyword"), py::arg("py_data"), DeckKeyword_init_parser_keyword_pydata_int_docstring)
233235

234-
.def(py::init([](const ParserKeyword& parser_keyword, py::array_t<double> py_data, UnitSystem& active_system, UnitSystem& default_system) {
236+
.def(py::init([](const ParserKeyword& parser_keyword, py::array_t<double> py_data, UnitSystem& active_system, UnitSystem& default_system) {
235237
return DeckKeyword(parser_keyword, convert::vector(py_data), active_system, default_system);
236-
} ) )
238+
}), py::arg("parser_keyword"), py::arg("py_data"), py::arg("active_system"), py::arg("default_system"), DeckKeyword_init_parser_keyword_pydata_double_docstring)
237239

238-
.def("get_int_array", &get_int_array)
239-
.def("get_raw_array", &get_raw_array)
240-
.def("get_SI_array", &get_SI_array)
241-
;
240+
.def("get_int_array", &get_int_array, DeckKeyword_get_int_array_docstring)
241+
.def("get_raw_array", &get_raw_array, DeckKeyword_get_raw_array_docstring)
242+
.def("get_SI_array", &get_SI_array, DeckKeyword_get_SI_array_docstring);
242243

243244

244245
py::class_< DeckRecord >( module, "DeckRecord")
@@ -249,26 +250,26 @@ void python::common::export_DeckKeyword(py::module& module) {
249250
;
250251

251252

252-
py::class_< DeckItem >(module, "DeckItem")
253-
.def( "__len__", &DeckItem::data_size )
254-
.def("is_uda", &DeckItem::is_uda)
255-
.def("is_double", &DeckItem::is_double)
256-
.def("is_int", &DeckItem::is_int)
257-
.def("is_string", &DeckItem::is_string)
258-
.def("get_str", &get_string)
259-
.def("get_int", &DeckItem::get<int>)
260-
.def("get_raw", &DeckItem::get<double>)
261-
.def("get_uda", &DeckItem::get<UDAValue>)
262-
.def("get_SI", &DeckItem::getSIDouble)
263-
.def("get_data_list", &item_to_pylist)
264-
.def("get_raw_data_list", &raw_data_to_pylist)
265-
.def("get_SI_data_list", &SI_data_to_pylist)
266-
.def("__has_value", &DeckItem::hasValue)
267-
.def("__defaulted", &DeckItem::defaultApplied)
268-
.def("__is_numeric", &uda_item_is_numeric)
269-
.def("__uda_double", &get_uda_double)
270-
.def("__uda_str", &get_uda_str)
271-
.def("name", &DeckItem::name)
253+
py::class_<DeckItem>(module, "DeckItem", DeckItem_docstring)
254+
.def("__len__", &DeckItem::data_size, DeckItem_len_docstring)
255+
.def("is_uda", &DeckItem::is_uda, DeckItem_is_uda_docstring)
256+
.def("is_double", &DeckItem::is_double, DeckItem_is_double_docstring)
257+
.def("is_int", &DeckItem::is_int, DeckItem_is_int_docstring)
258+
.def("is_string", &DeckItem::is_string, DeckItem_is_string_docstring)
259+
.def("get_str", &get_string, py::arg("index"), DeckItem_get_str_docstring)
260+
.def("get_int", &DeckItem::get<int>, py::arg("index"), DeckItem_get_int_docstring)
261+
.def("get_raw", &DeckItem::get<double>, py::arg("index"), DeckItem_get_raw_docstring)
262+
.def("get_uda", &DeckItem::get<UDAValue>, py::arg("index"), DeckItem_get_uda_docstring)
263+
.def("get_SI", &DeckItem::getSIDouble, py::arg("index"), DeckItem_get_SI_docstring)
264+
.def("get_data_list", &item_to_pylist, DeckItem_get_data_list_docstring)
265+
.def("get_raw_data_list", &raw_data_to_pylist, DeckItem_get_raw_data_list_docstring)
266+
.def("get_SI_data_list", &SI_data_to_pylist, DeckItem_get_SI_data_list_docstring)
267+
.def("__has_value", &DeckItem::hasValue, py::arg("index"), DeckItem_has_value_docstring)
268+
.def("__defaulted", &DeckItem::defaultApplied, py::arg("index"), DeckItem_defaulted_docstring)
269+
.def("__is_numeric", &uda_item_is_numeric, DeckItem_is_numeric_docstring)
270+
.def("__uda_double", &get_uda_double, DeckItem_uda_double_docstring)
271+
.def("__uda_str", &get_uda_str, DeckItem_uda_str_docstring)
272+
.def("name", &DeckItem::name, DeckItem_name_docstring)
272273
;
273274

274275

‎python/cxx/schedule.cpp‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -209,30 +209,30 @@ void python::common::export_Schedule(py::module& module) {
209209
py::class_< Schedule, std::shared_ptr<Schedule> >( module, "Schedule", ScheduleClass_docstring)
210210
.def(py::init<const Deck&, const EclipseState& >(), py::arg("deck"), py::arg("eclipse_state"))
211211
.def("_groups", &get_groups, py::arg("report_step"), Schedule_groups_docstring)
212-
.def_property_readonly( "start", &get_start_time )
213-
.def_property_readonly( "end", &get_end_time )
212+
.def_property_readonly("start", &get_start_time, Schedule_start_docstring)
213+
.def_property_readonly("end", &get_end_time, Schedule_end_docstring)
214214
.def_property_readonly("timesteps", [](const Schedule& self) {
215215
py::print("The property 'timesteps' is deprecated, since the name is misleading. This actually returns the report steps, so use 'reportsteps' instead!");
216216
return get_reportsteps(self);
217217
}) // Deprecated since the name is misleading, this function actually returns the report steps
218-
.def_property_readonly( "reportsteps", &get_reportsteps )
219-
.def("__len__", &Schedule::size)
218+
.def_property_readonly("reportsteps", &get_reportsteps, Schedule_reportsteps_docstring)
219+
.def("__len__", &Schedule::size, Schedule_len_docstring)
220220
.def("__getitem__", &getitem, py::arg("report_step"), Schedule_getitem_docstring)
221221
.def("shut_well", py::overload_cast<const std::string&, std::size_t>(&Schedule::shut_well), py::arg("well_name"), py::arg("step"), Schedule_shut_well_well_name_step_docstring)
222222
.def("shut_well", py::overload_cast<const std::string&>(&Schedule::shut_well), py::arg("well_name"), Schedule_shut_well_well_name_docstring)
223223
.def("open_well", py::overload_cast<const std::string&, std::size_t>(&Schedule::open_well), py::arg("well_name"), py::arg("step"), Schedule_open_well_well_name_step_docstring)
224224
.def("open_well", py::overload_cast<const std::string&>(&Schedule::open_well), py::arg("well_name"), Schedule_open_well_well_name_docstring)
225225
.def("stop_well", py::overload_cast<const std::string&, std::size_t>(&Schedule::stop_well), py::arg("well_name"), py::arg("step"), Schedule_stop_well_well_name_step_docstring)
226226
.def("stop_well", py::overload_cast<const std::string&>(&Schedule::stop_well), py::arg("well_name"), Schedule_stop_well_well_name_docstring)
227-
.def( "get_wells", &Schedule::getWells, py::arg("well_name_pattern"), Schedule_get_wells_docstring)
228-
.def( "get_injection_properties", &get_injection_properties, py::arg("well_name"), py::arg("report_step"), Schedule_get_injection_properties_docstring)
229-
.def( "get_production_properties", &get_production_properties, py::arg("well_name"), py::arg("report_step"), Schedule_get_production_properties_docstring)
230-
.def("well_names", py::overload_cast<const std::string&>(&Schedule::wellNames, py::const_), py::arg("well_name_pattern"))
231-
.def( "get_well", &get_well, py::arg("well_name"), py::arg("report_step"), Schedule_get_well_docstring)
232-
.def( "insert_keywords", py::overload_cast<Schedule&, py::list&, std::size_t>(&insert_keywords), py::arg("keywords"), py::arg("step"))
233-
.def( "insert_keywords", py::overload_cast<Schedule&, const std::string&, std::size_t, const UnitSystem&>(&insert_keywords), py::arg("data"), py::arg("step"), py::arg("unit_system"))
234-
.def( "insert_keywords", py::overload_cast<Schedule&, const std::string&, std::size_t>(&insert_keywords), py::arg("data"), py::arg("step"))
235-
.def( "insert_keywords", py::overload_cast<Schedule&, const std::string&>(&insert_keywords),py::arg("data"))
236-
.def("__contains__", &has_well, py::arg("well_name"))
227+
.def("get_wells", &Schedule::getWells, py::arg("report_step"), Schedule_get_wells_docstring)
228+
.def("get_injection_properties", &get_injection_properties, py::arg("well_name"), py::arg("report_step"), Schedule_get_injection_properties_docstring)
229+
.def("get_production_properties", &get_production_properties, py::arg("well_name"), py::arg("report_step"), Schedule_get_production_properties_docstring)
230+
.def("well_names", py::overload_cast<const std::string&>(&Schedule::wellNames, py::const_), py::arg("well_name_pattern"), Schedule_well_names_docstring)
231+
.def("get_well", &get_well, py::arg("well_name"), py::arg("report_step"), Schedule_get_well_docstring)
232+
.def("insert_keywords", py::overload_cast<Schedule&, py::list&, std::size_t>(&insert_keywords), py::arg("keywords"), py::arg("step"), Schedule_insert_keywords_list_docstring)
233+
.def("insert_keywords", py::overload_cast<Schedule&, const std::string&, std::size_t, const UnitSystem&>(&insert_keywords), py::arg("data"), py::arg("step"), py::arg("unit_system"), Schedule_insert_keywords_data_step_unit_system_docstring)
234+
.def("insert_keywords", py::overload_cast<Schedule&, const std::string&, std::size_t>(&insert_keywords), py::arg("data"), py::arg("step"), Schedule_insert_keywords_data_step_docstring)
235+
.def("insert_keywords", py::overload_cast<Schedule&, const std::string&>(&insert_keywords),py::arg("data"), Schedule_insert_keywords_data_docstring)
236+
.def("__contains__", &has_well, py::arg("well_name"), Schedule_contains_docstring)
237237
;
238238
}

‎python/cxx/summary_state.cpp‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -48,18 +48,18 @@ void python::common::export_SummaryState(py::module& module) {
4848

4949
py::class_<SummaryState, std::shared_ptr<SummaryState>>(module, "SummaryState", SummaryStateClass_docstring)
5050
.def(py::init<std::time_t>())
51-
.def("update", &SummaryState::update)
51+
.def("update", &SummaryState::update, py::arg("variable_name"), py::arg("value"), SummaryState_update_docstring)
5252
.def("update_well_var", &SummaryState::update_well_var, py::arg("well_name"), py::arg("variable_name"), py::arg("new_value"), SummaryState_update_well_var_docstring)
5353
.def("update_group_var", &SummaryState::update_group_var, py::arg("group_name"), py::arg("variable_name"), py::arg("new_value"), SummaryState_update_group_var_docstring)
5454
.def("well_var", py::overload_cast<const std::string&, const std::string&>(&SummaryState::get_well_var, py::const_), py::arg("well_name"), py::arg("variable_name"), SummaryState_well_var_docstring)
5555
.def("group_var", py::overload_cast<const std::string&, const std::string&>(&SummaryState::get_group_var, py::const_), py::arg("group_name"), py::arg("variable_name"), SummaryState_group_var_docstring)
5656
.def("elapsed", &SummaryState::get_elapsed, SummaryState_elapsed_docstring)
5757
.def_property_readonly("groups", groups, SummaryState_groups_docstring)
5858
.def_property_readonly("wells", wells, SummaryState_wells_docstring)
59-
.def("__contains__", &SummaryState::has)
59+
.def("__contains__", &SummaryState::has, py::arg("variable_name"), SummaryState_contains_docstring)
6060
.def("has_well_var", py::overload_cast<const std::string&, const std::string&>(&SummaryState::has_well_var, py::const_), py::arg("well_name"), py::arg("variable_name"), SummaryState_has_well_var_docstring)
6161
.def("has_group_var", py::overload_cast<const std::string&, const std::string&>(&SummaryState::has_group_var, py::const_), py::arg("group_name"), py::arg("variable_name"), SummaryState_has_group_var_docstring)
62-
.def("__setitem__", &SummaryState::set)
63-
.def("__getitem__", py::overload_cast<const std::string&>(&SummaryState::get, py::const_))
62+
.def("__setitem__", &SummaryState::set, py::arg("variable_name"), py::arg("new_value"), SummaryState_setitem_docstring)
63+
.def("__getitem__", py::overload_cast<const std::string&>(&SummaryState::get, py::const_), py::arg("variable_name"), SummaryState_getitem_docstring)
6464
;
6565
}

0 commit comments

Comments
 (0)