This is an archive of the discontinued Mercurial Phabricator instance.

Differential D5546

rust-cpython: rustdoc improvements
ClosedPublic

Authored by gracinet on Jan 10 2019, 4:55 AM.

Details

Reviewers
None
Group Reviewers
hg-reviewers
Commits
rHGdcf818267bc1: rust-cpython: rustdoc improvements
Summary

By default, cargo doc builds the documentation for public
constructs only, so we make public those that can. Since cindex
is not safe, we keep it private.

Unfortunately, the macro syntax of rust-cpython doesn't allow us
to document the classes directly, so we resort to do that at
the module level.

Diff Detail

Repository
rHG Mercurial
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

gracinet created this revision.Jan 10 2019, 4:55 AM
Closed by commit rHGdcf818267bc1: rust-cpython: rustdoc improvements (authored by gracinet). · Explain WhyJan 11 2019, 9:15 AM
This revision was automatically updated to reflect the committed changes.

Revision Contents
Changeset List

Diff 13170

rust/hg-cpython/src/ancestors.rs

// ancestors.rs // ancestors.rs
// //
// Copyright 2018 Georges Racinet <gracinet@anybox.fr> // Copyright 2018 Georges Racinet <gracinet@anybox.fr>
// //
// This software may be used and distributed according to the terms of the // This software may be used and distributed according to the terms of the
// GNU General Public License version 2 or any later version. // GNU General Public License version 2 or any later version.
//! Bindings for the hg::ancestors module provided by the //! Bindings for the `hg::ancestors` module provided by the
//! `hg-core` crate. From Python, this will be seen as `rustext.ancestor` //! `hg-core` crate. From Python, this will be seen as `rustext.ancestor`
//! and can be used as replacement for the the pure `ancestor` Python module.
//!
//! # Classes visible from Python:
//! - [`LazyAncestors`] is the Rust implementation of
//! `mercurial.ancestor.lazyancestors`.
//! The only difference is that it is instantiated with a C `parsers.index`
//! instance instead of a parents function.
//!
//! - [`AncestorsIterator`] is the Rust counterpart of the
//! `ancestor._lazyancestorsiter` Python generator.
//! From Python, instances of this should be mainly obtained by calling
//! `iter()` on a [`LazyAncestors`] instance.
//!
//! [`LazyAncestors`]: struct.LazyAncestors.html
//! [`AncestorsIterator`]: struct.AncestorsIterator.html
use cindex::Index; use cindex::Index;
use cpython::{ use cpython::{
ObjectProtocol, PyClone, PyDict, PyModule, PyObject, PyResult, Python, ObjectProtocol, PyClone, PyDict, PyModule, PyObject, PyResult, Python,
}; };
use exceptions::GraphError; use exceptions::GraphError;
use hg; use hg;
use hg::Revision; use hg::Revision;
use hg::{AncestorsIterator as CoreIterator, LazyAncestors as CoreLazy}; use hg::{AncestorsIterator as CoreIterator, LazyAncestors as CoreLazy};
use std::cell::RefCell; use std::cell::RefCell;
/// Utility function to convert a Python iterable into a Vec<Revision> /// Utility function to convert a Python iterable into a Vec<Revision>
/// ///
/// We need this to feed to AncestorIterators constructors because /// We need this to feed to `AncestorIterators` constructors because
/// a PyErr can arise at each step of iteration, whereas our inner objects /// a `PyErr` can arise at each step of iteration, whereas our inner objects
/// expect iterables over Revision, not over some Result<Revision, PyErr> /// expect iterables over `Revision`, not over some `Result<Revision, PyErr>`
fn reviter_to_revvec(py: Python, revs: PyObject) -> PyResult<Vec<Revision>> { fn reviter_to_revvec(py: Python, revs: PyObject) -> PyResult<Vec<Revision>> {
revs.iter(py)? revs.iter(py)?
.map(|r| r.and_then(|o| o.extract::<Revision>(py))) .map(|r| r.and_then(|o| o.extract::<Revision>(py)))
.collect() .collect()
} }
py_class!(class AncestorsIterator |py| { py_class!(pub class AncestorsIterator |py| {
// TODO RW lock ? // TODO RW lock ?
data inner: RefCell<Box<CoreIterator<Index>>>; data inner: RefCell<Box<CoreIterator<Index>>>;
def __next__(&self) -> PyResult<Option<Revision>> { def __next__(&self) -> PyResult<Option<Revision>> {
match self.inner(py).borrow_mut().next() { match self.inner(py).borrow_mut().next() {
Some(Err(e)) => Err(GraphError::pynew(py, e)), Some(Err(e)) => Err(GraphError::pynew(py, e)),
None => Ok(None), None => Ok(None),
Some(Ok(r)) => Ok(Some(r)), Some(Ok(r)) => Ok(Some(r)),
}); });
impl AncestorsIterator { impl AncestorsIterator {
pub fn from_inner(py: Python, ait: CoreIterator<Index>) -> PyResult<Self> { pub fn from_inner(py: Python, ait: CoreIterator<Index>) -> PyResult<Self> {
Self::create_instance(py, RefCell::new(Box::new(ait))) Self::create_instance(py, RefCell::new(Box::new(ait)))
} }
} }
py_class!(class LazyAncestors |py| { py_class!(pub class LazyAncestors |py| {
data inner: RefCell<Box<CoreLazy<Index>>>; data inner: RefCell<Box<CoreLazy<Index>>>;
def __contains__(&self, rev: Revision) -> PyResult<bool> { def __contains__(&self, rev: Revision) -> PyResult<bool> {
self.inner(py) self.inner(py)
.borrow_mut() .borrow_mut()
.contains(rev) .contains(rev)
.map_err(|e| GraphError::pynew(py, e)) .map_err(|e| GraphError::pynew(py, e))
} }
CoreLazy::new(Index::new(py, index)?, initvec, stoprev, inclusive) CoreLazy::new(Index::new(py, index)?, initvec, stoprev, inclusive)
.map_err(|e| GraphError::pynew(py, e))?; .map_err(|e| GraphError::pynew(py, e))?;
Self::create_instance(py, RefCell::new(Box::new(lazy))) Self::create_instance(py, RefCell::new(Box::new(lazy)))
} }
}); });
/// Create the module, with __package__ given from parent /// Create the module, with `__package__` given from parent
pub fn init_module(py: Python, package: &str) -> PyResult<PyModule> { pub fn init_module(py: Python, package: &str) -> PyResult<PyModule> {
let dotted_name = &format!("{}.ancestor", package); let dotted_name = &format!("{}.ancestor", package);
let m = PyModule::new(py, dotted_name)?; let m = PyModule::new(py, dotted_name)?;
m.add(py, "__package__", package)?; m.add(py, "__package__", package)?;
m.add( m.add(
py, py,
"__doc__", "__doc__",
"Generic DAG ancestor algorithms - Rust implementation", "Generic DAG ancestor algorithms - Rust implementation",

rust/hg-cpython/src/exceptions.rs

// ancestors.rs
//
// Copyright 2018 Georges Racinet <gracinet@anybox.fr>
//
// This software may be used and distributed according to the terms of the
// GNU General Public License version 2 or any later version.
//! Bindings for Rust errors
//!
//! [`GraphError`] exposes `hg::GraphError` as a subclass of `ValueError`
//!
//! [`GraphError`]: struct.GraphError.html
use cpython::exc::ValueError; use cpython::exc::ValueError;
use cpython::{PyErr, Python}; use cpython::{PyErr, Python};
use hg; use hg;
py_exception!(rustext, GraphError, ValueError); py_exception!(rustext, GraphError, ValueError);
impl GraphError { impl GraphError {
pub fn pynew(py: Python, inner: hg::GraphError) -> PyErr { pub fn pynew(py: Python, inner: hg::GraphError) -> PyErr {
match inner { match inner {
hg::GraphError::ParentOutOfRange(r) => { hg::GraphError::ParentOutOfRange(r) => {
GraphError::new(py, ("ParentOutOfRange", r)) GraphError::new(py, ("ParentOutOfRange", r))
} }
} }
} }
} }

rust/hg-cpython/src/lib.rs

// lib.rs // lib.rs
// //
// Copyright 2018 Georges Racinet <gracinet@anybox.fr> // Copyright 2018 Georges Racinet <gracinet@anybox.fr>
// //
// This software may be used and distributed according to the terms of the // This software may be used and distributed according to the terms of the
// GNU General Public License version 2 or any later version. // GNU General Public License version 2 or any later version.
//! Python bindings of `hg-core` objects using the `cpython` crate. //! Python bindings of `hg-core` objects using the `cpython` crate.
//! Once compiled, the resulting single shared library object can be placed in //! Once compiled, the resulting single shared library object can be placed in
//! the `mercurial` package directly as `rustext.so` or `rustext.dll`. //! the `mercurial` package directly as `rustext.so` or `rustext.dll`.
//! It holds several modules, so that from the point of view of Python, //! It holds several modules, so that from the point of view of Python,
//! it behaves as the `cext` package. //! it behaves as the `cext` package.
//! //!
//! Example: //! Example:
//! ``` //!
//! ```text
//! >>> from mercurial.rustext import ancestor //! >>> from mercurial.rustext import ancestor
//! >>> ancestor.__doc__ //! >>> ancestor.__doc__
//! 'Generic DAG ancestor algorithms - Rust implementation' //! 'Generic DAG ancestor algorithms - Rust implementation'
//! ``` //! ```
#[macro_use] #[macro_use]
extern crate cpython; extern crate cpython;
extern crate hg; extern crate hg;
extern crate libc; extern crate libc;
mod ancestors; pub mod ancestors;
mod cindex; mod cindex;
mod exceptions; pub mod exceptions;
py_module_initializer!(rustext, initrustext, PyInit_rustext, |py, m| { py_module_initializer!(rustext, initrustext, PyInit_rustext, |py, m| {
m.add( m.add(
py, py,
"__doc__", "__doc__",
"Mercurial core concepts - Rust implementation", "Mercurial core concepts - Rust implementation",
)?; )?;
let dotted_name: String = m.get(py, "__name__")?.extract(py)?; let dotted_name: String = m.get(py, "__name__")?.extract(py)?;
m.add(py, "ancestor", ancestors::init_module(py, &dotted_name)?)?; m.add(py, "ancestor", ancestors::init_module(py, &dotted_name)?)?;
m.add(py, "GraphError", py.get_type::<exceptions::GraphError>())?; m.add(py, "GraphError", py.get_type::<exceptions::GraphError>())?;
Ok(()) Ok(())
}); });