aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAvatar Piotr Jaroszyński <peper@gentoo.org> 2007-06-18 14:22:33 +0000
committerAvatar Piotr Jaroszyński <peper@gentoo.org> 2007-06-18 14:22:33 +0000
commit054d9bc46432020a8ead1b5fcdae15aa7e869774 (patch)
tree6fe199a2f7cda183f67ef4afb2e5772af8af0002
parentaf887eb85074359917d6d08b5b0a2ab74385b436 (diff)
downloadpaludis-054d9bc46432020a8ead1b5fcdae15aa7e869774.tar.gz
paludis-054d9bc46432020a8ead1b5fcdae15aa7e869774.tar.xz
(python) Add docstrings to the exceptions.
-rw-r--r--python/dep_spec.cc3
-rw-r--r--python/environment.cc15
-rw-r--r--python/exception.cc18
-rw-r--r--python/exception.hh15
-rw-r--r--python/fs_entry.cc3
-rw-r--r--python/name.cc28
-rw-r--r--python/package_database.cc19
-rw-r--r--python/portage_dep_parser.cc12
-rw-r--r--python/repository.cc18
-rw-r--r--python/version_operator.cc3
-rw-r--r--python/version_spec.cc3
11 files changed, 92 insertions, 45 deletions
diff --git a/python/dep_spec.cc b/python/dep_spec.cc
index 6acb941..d5bbea7 100644
--- a/python/dep_spec.cc
+++ b/python/dep_spec.cc
@@ -600,7 +600,8 @@ struct PackageDepSpecSPFromPython
void PALUDIS_VISIBLE expose_dep_spec()
{
ExceptionRegister::get_instance()->add_exception<PackageDepSpecError>
- ("PackageDepSpecError", "BaseException");
+ ("PackageDepSpecError", "BaseException",
+ "Thrown if an invalid package dep spec specification is encountered.");
enum_auto("PackageDepSpecParseMode", last_pds_pm);
diff --git a/python/environment.cc b/python/environment.cc
index edddce9..cbac1fa 100644
--- a/python/environment.cc
+++ b/python/environment.cc
@@ -45,15 +45,20 @@ struct NoConfigEnvironmentWrapper :
void PALUDIS_VISIBLE expose_environment()
{
ExceptionRegister::get_instance()->add_exception<NoSuchEnvironmentTypeError>
- ("NoSuchEnvironmentTypeError", "ConfigurationError");
+ ("NoSuchEnvironmentTypeError", "ConfigurationError",
+ "Thrown if an environment of the specified type does not exist.");
ExceptionRegister::get_instance()->add_exception<PaludisEnvironmentSoDirNotADirectoryError>
- ("PaludisEnvironmentSoDirNotADirectoryError", "BaseException");
+ ("PaludisEnvironmentSoDirNotADirectoryError", "BaseException",
+ "Thrown if PALUDIS_ENVIRONMENT_SO_DIR is not a directory.");
ExceptionRegister::get_instance()->add_exception<PaludisEnvironmentSoDirCannotDlopenError>
- ("PaludisEnvironmentSoDirCannotDlopenError", "BaseException");
+ ("PaludisEnvironmentSoDirCannotDlopenError", "BaseException",
+ "Thrown if a repository .so cannot be used.");
ExceptionRegister::get_instance()->add_exception<paludis_environment::PaludisConfigError>
- ("PaludisConfigError", "ConfigurationError");
+ ("PaludisConfigError", "ConfigurationError",
+ "Thrown if a configuration error is encountered by PaludisConfig.");
ExceptionRegister::get_instance()->add_exception<paludis_environment::PaludisConfigNoDirectoryError>
- ("PaludisConfigNoDirectoryError", "PaludisConfigError");
+ ("PaludisConfigNoDirectoryError", "PaludisConfigError",
+ "Thrown if the config directory cannot be found by PaludisConfig.");
bp::class_<EnvironmentMaker, boost::noncopyable> em("EnvironmentMaker",
"Virtual constructor for environments.",
diff --git a/python/exception.cc b/python/exception.cc
index 8c61c26..83c4857 100644
--- a/python/exception.cc
+++ b/python/exception.cc
@@ -69,9 +69,17 @@ ExceptionRegister::get_py_exception(const std::string & name)
void PALUDIS_VISIBLE expose_exception()
{
- ExceptionRegister::get_instance()->add_exception<Exception>("BaseException");
- ExceptionRegister::get_instance()->add_exception<InternalError>("InternalError", "BaseException");
- ExceptionRegister::get_instance()->add_exception<NotAvailableError>("NotAvailableError", "BaseException");
- ExceptionRegister::get_instance()->add_exception<NameError>("NameError", "BaseException");
- ExceptionRegister::get_instance()->add_exception<ConfigurationError>("ConfigurationError", "BaseException");
+ ExceptionRegister::get_instance()->add_exception<Exception>("BaseException",
+ "Base exception class.");
+ ExceptionRegister::get_instance()->add_exception<InternalError>("InternalError", "BaseException",
+ "An InternalError is an Exception that is thrown if something "
+ "that is never supposed to happen happens.");
+ ExceptionRegister::get_instance()->add_exception<NotAvailableError>("NotAvailableError", "BaseException",
+ "A NotAvailableError is an Exception that is thrown if something "
+ "that is not available (for example due to compile time configure options "
+ "or platform limitations) is used.");
+ ExceptionRegister::get_instance()->add_exception<NameError>("NameError", "BaseException",
+ "A NameError is an Exception that is thrown when some kind of invalid name is encountered.");
+ ExceptionRegister::get_instance()->add_exception<ConfigurationError>("ConfigurationError", "BaseException",
+ "A ConfigurationError is thrown when an invalid configuration occurs.");
}
diff --git a/python/exception.hh b/python/exception.hh
index c3dcfb8..62a9cde 100644
--- a/python/exception.hh
+++ b/python/exception.hh
@@ -49,7 +49,7 @@ namespace paludis
PyObject * _e;
public:
- RegisteredException(const std::string & name, PyObject * base);
+ RegisteredException(const std::string & name, const std::string & doc, PyObject * base);
void translator(const Ex_ & x) const;
@@ -61,12 +61,15 @@ namespace paludis
};
template <class Ex_>
- RegisteredException<Ex_>::RegisteredException(const std::string & name, PyObject * base=NULL) :
+ RegisteredException<Ex_>::RegisteredException(const std::string & name,
+ const std::string & doc, PyObject * base) :
_name(name),
_longname("paludis." + name),
_e(PyErr_NewException(const_cast<char*>(_longname.c_str()), base, NULL))
{
PyModule_AddObject(boost::python::detail::current_scope, const_cast<char*>(_name.c_str()), _e);
+ PyObject * doc_string = PyString_FromString(doc.c_str());
+ PyObject_SetAttrString(_e, "__doc__", doc_string);
boost::python::register_exception_translator<Ex_>(
tr1::bind(tr1::mem_fn(&RegisteredException<Ex_>::translator),
this, tr1::placeholders::_1)
@@ -103,17 +106,17 @@ namespace paludis
~ExceptionRegister();
template <typename Ex_>
- void add_exception(const std::string & name)
+ void add_exception(const std::string & name, const std::string & doc)
{
add_map_item(name, tr1::shared_ptr<RegisteredExceptionBase>(
- new RegisteredException<Ex_>(name)));
+ new RegisteredException<Ex_>(name, doc, 0)));
}
template <typename Ex_>
- void add_exception(const std::string & name, const std::string & base)
+ void add_exception(const std::string & name, const std::string & base, const std::string & doc)
{
add_map_item(name, tr1::shared_ptr<RegisteredExceptionBase>(
- new RegisteredException<Ex_>(name, get_py_exception(base))));
+ new RegisteredException<Ex_>(name, doc, get_py_exception(base))));
}
};
}
diff --git a/python/fs_entry.cc b/python/fs_entry.cc
index fb9136d..4c98269 100644
--- a/python/fs_entry.cc
+++ b/python/fs_entry.cc
@@ -28,7 +28,8 @@ namespace bp = boost::python;
void PALUDIS_VISIBLE expose_fs_entry()
{
ExceptionRegister::get_instance()->add_exception<FSError>
- ("FSError", "BaseException");
+ ("FSError", "BaseException",
+ "Generic filesystem error class.");
bp::implicitly_convertible<std::string, FSEntry>();
bp::to_python_converter<FSEntry, to_string<FSEntry> >();
diff --git a/python/name.cc b/python/name.cc
index 0df086c..037227c 100644
--- a/python/name.cc
+++ b/python/name.cc
@@ -28,23 +28,33 @@ namespace bp = boost::python;
void PALUDIS_VISIBLE expose_name()
{
ExceptionRegister::get_instance()->add_exception<PackageNamePartError>
- ("PackageNamePartError", "NameError");
+ ("PackageNamePartError", "NameError",
+ "Thrown if an invalid value is assigned to a PackageNamePart.");
ExceptionRegister::get_instance()->add_exception<CategoryNamePartError>
- ("CategoryNamePartError", "NameError");
+ ("CategoryNamePartError", "NameError",
+ "Thrown if an invalid value is assigned to a CategoryNamePart.");
ExceptionRegister::get_instance()->add_exception<QualifiedPackageNameError>
- ("QualifiedPackageNameError", "NameError");
+ ("QualifiedPackageNameError", "NameError",
+ "May be thrown if an invalid name is assigned to a QualifiedPackageName "
+ "(alternatively, the exception raised may be a PackageNamePartError or a CategoryNamePartError).");
ExceptionRegister::get_instance()->add_exception<UseFlagNameError>
- ("UseFlagNameError", "NameError");
+ ("UseFlagNameError", "NameError",
+ "Thrown if an invalid value is assigned to a UseFlagName.");
ExceptionRegister::get_instance()->add_exception<IUseFlagNameError>
- ("IUseFlagNameError", "NameError");
+ ("IUseFlagNameError", "NameError",
+ "Thrown if an invalid value is assigned to a IUseFlagName.");
ExceptionRegister::get_instance()->add_exception<SlotNameError>
- ("SlotNameError", "NameError");
+ ("SlotNameError", "NameError",
+ "Thrown if an invalid value is assigned to a SlotName.");
ExceptionRegister::get_instance()->add_exception<RepositoryNameError>
- ("RepositoryNameError", "NameError");
+ ("RepositoryNameError", "NameError",
+ "Thrown if an invalid value is assigned to a RepositoryName.");
ExceptionRegister::get_instance()->add_exception<KeywordNameError>
- ("KeywordNameError", "NameError");
+ ("KeywordNameError", "NameError",
+ "Thrown if an invalid value is assigned to a KeywordName.");
ExceptionRegister::get_instance()->add_exception<SetNameError>
- ("SetNameError", "NameError");
+ ("SetNameError", "NameError",
+ "Thrown if an invalid value is assigned to a SetName.");
class_validated<PackageNamePart>
pnp("PackageNamePart",
diff --git a/python/package_database.cc b/python/package_database.cc
index 4ebc26f..1583825 100644
--- a/python/package_database.cc
+++ b/python/package_database.cc
@@ -34,17 +34,24 @@ namespace bp = boost::python;
void PALUDIS_VISIBLE expose_package_database()
{
ExceptionRegister::get_instance()->add_exception<PackageDatabaseError>
- ("PackageDatabaseError", "BaseException");
+ ("PackageDatabaseError", "BaseException",
+ "A PackageDatabaseError is an error that occurs when performing some operation upon a PackageDatabase.");
ExceptionRegister::get_instance()->add_exception<DuplicateRepositoryError>
- ("DuplicateRepositoryError", "PackageDatabaseError");
+ ("DuplicateRepositoryError", "PackageDatabaseError",
+ "Thrown if a Repository with the same name as an existing member is added to a PackageDatabase.");
ExceptionRegister::get_instance()->add_exception<PackageDatabaseLookupError>
- ("PackageDatabaseLookupError", "PackageDatabaseError");
+ ("PackageDatabaseLookupError", "PackageDatabaseError",
+ "A PackageDatabaseLookupError descendent is thrown if an error occurs "
+ "when looking for something in a PackageDatabase.");
ExceptionRegister::get_instance()->add_exception<AmbiguousPackageNameError>
- ("AmbiguousPackageNameError", "PackageDatabaseLookupError");
+ ("AmbiguousPackageNameError", "PackageDatabaseLookupError",
+ "Thrown if a PackageDatabase query results in more than one matching Package.");
ExceptionRegister::get_instance()->add_exception<NoSuchPackageError>
- ("NoSuchPackageError", "PackageDatabaseLookupError");
+ ("NoSuchPackageError", "PackageDatabaseLookupError",
+ "Thrown if there is no Package in a PackageDatabase with the given name.");
ExceptionRegister::get_instance()->add_exception<NoSuchRepositoryError>
- ("NoSuchRepositoryError", "PackageDatabaseLookupError");
+ ("NoSuchRepositoryError", "PackageDatabaseLookupError",
+ "Thrown if there is no Repository in a RepositoryDatabase with the given name.");
enum_auto("QueryOrder", last_qo);
diff --git a/python/portage_dep_parser.cc b/python/portage_dep_parser.cc
index d75707f..9ddc4d3 100644
--- a/python/portage_dep_parser.cc
+++ b/python/portage_dep_parser.cc
@@ -30,13 +30,17 @@ namespace bp = boost::python;
void PALUDIS_VISIBLE expose_portage_dep_parser()
{
ExceptionRegister::get_instance()->add_exception<DepStringError>
- ("DepStringError", "BaseException");
+ ("DepStringError", "BaseException",
+ "A DepStringError descendent is thrown if an invalid depend string is encountered.");
ExceptionRegister::get_instance()->add_exception<DepStringLexError>
- ("DepStringLexError", "DepStringError");
+ ("DepStringLexError", "DepStringError",
+ "A DepStringLexError is thrown if a lex-level error is encountered when parsing a dependency string.");
ExceptionRegister::get_instance()->add_exception<DepStringParseError>
- ("DepStringParseError", "DepStringError");
+ ("DepStringParseError", "DepStringError",
+ "Thrown if an error is encountered when parsing a dependency string.");
ExceptionRegister::get_instance()->add_exception<DepStringNestingError>
- ("DepStringNestingError", "DepStringParseError");
+ ("DepStringNestingError", "DepStringParseError",
+ "Thrown if a dependency string does not have properly balanced parentheses.");
bp::class_<PortageDepParser, boost::noncopyable>
pdp("PortageDepParser",
diff --git a/python/repository.cc b/python/repository.cc
index 0ccd35c..437e226 100644
--- a/python/repository.cc
+++ b/python/repository.cc
@@ -201,17 +201,23 @@ struct RepositoryPortageInterfaceWrapper :
void PALUDIS_VISIBLE expose_repository()
{
ExceptionRegister::get_instance()->add_exception<PackageActionError>
- ("PackageActionError", "BaseException");
+ ("PackageActionError", "BaseException",
+ "Parent class for install, uninstall errors.");
ExceptionRegister::get_instance()->add_exception<PackageInstallActionError>
- ("PackageInstallActionError", "PackageActionError");
+ ("PackageInstallActionError", "PackageActionError",
+ "Thrown if an install fails.");
ExceptionRegister::get_instance()->add_exception<PackageFetchActionError>
- ("PackageFetchActionError", "PackageActionError");
+ ("PackageFetchActionError", "PackageActionError",
+ "Thrown if a fetch fails.");
ExceptionRegister::get_instance()->add_exception<PackageUninstallActionError>
- ("PackageUninstallActionError", "PackageActionError");
+ ("PackageUninstallActionError", "PackageActionError",
+ "Thrown if an uninstall fails.");
ExceptionRegister::get_instance()->add_exception<PackageConfigActionError>
- ("PackageConfigActionError", "PackageActionError");
+ ("PackageConfigActionError", "PackageActionError",
+ "Thrown if a configure fails.");
ExceptionRegister::get_instance()->add_exception<EnvironmentVariableActionError>
- ("EnvironmentVariableActionError", "PackageActionError");
+ ("EnvironmentVariableActionError", "PackageActionError",
+ "Thrown if an environment variable query fails.");
class_collection<DestinationsCollection>
dc("DestinationsCollection",
diff --git a/python/version_operator.cc b/python/version_operator.cc
index 8aa29db..e6d1076 100644
--- a/python/version_operator.cc
+++ b/python/version_operator.cc
@@ -35,7 +35,8 @@ vo_compare(const VersionOperator & self, const VersionSpec & v1, const VersionSp
void PALUDIS_VISIBLE expose_version_operator()
{
ExceptionRegister::get_instance()->add_exception<BadVersionOperatorError>
- ("BadVersionOperatorError", "BaseException");
+ ("BadVersionOperatorError", "BaseException",
+ "Thrown if a bad version operator is encountered.");
enum_auto("VersionOperatorValue", last_vo);
diff --git a/python/version_spec.cc b/python/version_spec.cc
index ec0f030..cc0e0dd 100644
--- a/python/version_spec.cc
+++ b/python/version_spec.cc
@@ -28,7 +28,8 @@ namespace bp = boost::python;
void PALUDIS_VISIBLE expose_version_spec()
{
ExceptionRegister::get_instance()->add_exception<BadVersionSpecError>
- ("BadVersionSpecError", "BaseException");
+ ("BadVersionSpecError", "BaseException",
+ "Thrown if a VersionSpec is created from an invalid version string.");
bp::class_<VersionSpec>
vs("VersionSpec",