powerliners 0.2.12

// vim:fileencoding=utf-8:noet
//! Port of `powerline/lib/debug.py`.
//!
//! Upstream is a single function `print_cycles(objects, outstream,
//! show_progress)` that walks Python's GC referent graph to find
//! cyclic references — a Python-specific debugging tool relying on
//! `gc.get_referents()`, runtime introspection of `__dict__`, and
//! `id()`-based object identity.
//!
//! **Rust has no tracing garbage collector.** Cycles in Rust arise
//! only through `Rc`/`Arc` reference loops and are detected via:
//!   - `Weak` references that break the strong-count cycle, OR
//!   - external tools (Miri, Valgrind, address sanitizer) at debug time.
//!
//! The Python cycle-finder has no equivalent in Rust because the
//! premise — a runtime GC accumulating "garbage" objects with hidden
//! cyclic owners — does not exist. powerliners's memory model is
//! ownership + borrow checking; if a cycle compiles, it's intentional.
//!
//! This module therefore ports `print_cycles` as a documented no-op
//! that exists for upstream-API parity. Callers that exist solely to
//! invoke this fn (none in the current tree) are effectively unreachable.

// from __future__ import (unicode_literals, division, absolute_import, print_function)  // py:2
// import gc                                        // py:4
// import sys                                       // py:5
// from types import FrameType                      // py:7
// from itertools import chain                      // py:8

/// Port of `print_cycles()` from `powerline/lib/debug.py:12`.
///
/// **Rust port is a no-op** — see module-level doc-comment for the
/// rationale. The signature is preserved for upstream API parity, but
/// the body does nothing because Rust has no tracing GC and therefore
/// no cyclic-reference graph to walk.
///
/// :param list objects: ignored (no Rust analogue of `gc.garbage`)
/// :param file outstream: ignored
/// :param bool show_progress: ignored
pub fn print_cycles<W: std::io::Write>(
    _objects: &[serde_json::Value],
    _outstream: Option<&mut W>,
    _show_progress: bool,
) {
    // py:11  # From http://code.activestate.com/recipes/523004-find-cyclical-references/
    // py:12  def print_cycles(objects, outstream=sys.stdout, show_progress=False):
    // py:13-23  docstring
    // py:24  def print_path(path):
    // py:25  for i, step in enumerate(path):
    // py:26  # next "wraps around"
    // py:27  next = path[(i + 1) % len(path)]
    // py:29  outstream.write('	%s -- ' % str(type(step)))
    // py:30  written = False
    // py:31  if isinstance(step, dict):
    // py:32  for key, val in step.items():
    // py:33  if val is next:
    // py:34  outstream.write('[%s]' % repr(key))
    // py:35  written = True
    // py:36  break
    // py:37  if key is next:
    // py:38  outstream.write('[key] = %s' % repr(val))
    // py:39  written = True
    // py:40  break
    // py:41  elif isinstance(step, (list, tuple)):
    // py:42  for i, item in enumerate(step):
    // py:43  if item is next:
    // py:44  outstream.write('[%d]' % i)
    // py:45  written = True
    // py:46  elif getattr(type(step), '__getattribute__', None) in (object.__getattribute__, type.__getattribute__):
    // py:47  for attr in chain(dir(step), getattr(step, '__dict__', ())):
    // py:48  if getattr(step, attr, None) is next:
    // py:49  try:
    // py:50  outstream.write('%r.%s' % (step, attr))
    // py:51  except TypeError:
    // py:52  outstream.write('.%s' % (step, attr))
    // py:53  written = True
    // py:54  break
    // py:55  if not written:
    // py:56  outstream.write(repr(step))
    // py:57  outstream.write(' ->\n')
    // py:58  outstream.write('\n')
    // py:60  def recurse(obj, start, all, current_path):
    // py:61  if show_progress:
    // py:62  outstream.write('%d\r' % len(all))
    // py:64  all[id(obj)] = None
    // py:66  referents = gc.get_referents(obj)
    // py:67  for referent in referents:
    // py:68  # If we've found our way back to the start, this is
    // py:69  # a cycle, so print it out
    // py:70  if referent is start:
    // py:71  try:
    // py:72  outstream.write('Cyclic reference: %r\n' % referent)
    // py:73  except TypeError:
    // py:74  try:
    // py:75  outstream.write('Cyclic reference: %i (%r)\n' % (id(referent), type(referent)))
    // py:76  except TypeError:
    // py:77  outstream.write('Cyclic reference: %i\n' % id(referent))
    // py:78  print_path(current_path)
    // py:80  # Don't go back through the original list of objects, or
    // py:81  # through temporary references to the object, since those
    // py:82  # are just an artifact of the cycle detector itself.
    // py:83  elif referent is objects or isinstance(referent, FrameType):
    // py:84  continue
    // py:86  # We haven't seen this object before, so recurse
    // py:87  elif id(referent) not in all:
    // py:88  recurse(referent, start, all, current_path + (obj,))
    // py:90  for obj in objects:
    // py:91  # We are not interested in non-powerline cyclic references
    // py:92  try:
    // py:93  if not type(obj).__module__.startswith('powerline'):
    // py:94  continue
    // py:95  except AttributeError:
    // py:96  continue
    // py:97  recurse(obj, obj, {}, ())
}

/// Port of the inner `print_path()` closure from
/// `powerline/lib/debug.py:24-58`.
///
/// **Rust port is a no-op** — print_path walks Python's `dir(step)`,
/// `__dict__`, and per-element identity comparisons via `is`. All
/// three depend on the Python object model and have no Rust analog
/// for arbitrary `serde_json::Value` paths. The fn is surfaced for
/// upstream-API parity per the module-level rationale.
pub fn print_path<W: std::io::Write>(_path: &[serde_json::Value], _outstream: Option<&mut W>) {
    // py:24  def print_path(path):
    // py:25-58  walk + format — unreachable in Rust (see above)
}

/// Port of the inner `recurse()` closure from
/// `powerline/lib/debug.py:60-88`.
///
/// **Rust port is a no-op** — `recurse` calls `gc.get_referents()`
/// and `id()` which depend on Python's tracing GC. Rust has no such
/// runtime; ownership rules make the cycle-walk premise meaningless.
/// Surfaced for upstream-API parity per the module doc.
pub fn recurse<W: std::io::Write>(
    _obj: &serde_json::Value,
    _start: &serde_json::Value,
    _all: &mut std::collections::HashMap<usize, ()>,
    _current_path: &[serde_json::Value],
    _outstream: Option<&mut W>,
    _show_progress: bool,
) {
    // py:60  def recurse(obj, start, all, current_path):
    // py:61-88  walk gc.get_referents — unreachable in Rust
}

#[cfg(test)]
mod tests {
    use super::*;

    /// `print_cycles` is a documented no-op — verify it doesn't panic
    /// on any input shape.
    #[test]
    fn print_cycles_is_no_op() {
        let objects = vec![serde_json::json!({"a": 1}), serde_json::json!([1, 2, 3])];
        let mut buf: Vec<u8> = Vec::new();
        print_cycles(&objects, Some(&mut buf), false);
        assert!(buf.is_empty(), "Rust no-op should not produce output");
    }

    /// `print_path` and `recurse` are documented no-ops — verify the
    /// signatures hold and they don't panic.
    #[test]
    fn print_path_is_no_op() {
        let path = vec![serde_json::json!({"a": 1})];
        let mut buf: Vec<u8> = Vec::new();
        print_path(&path, Some(&mut buf));
        assert!(buf.is_empty());
    }

    #[test]
    fn recurse_is_no_op() {
        let obj = serde_json::json!({"a": 1});
        let start = obj.clone();
        let mut all = std::collections::HashMap::new();
        let path = Vec::new();
        let mut buf: Vec<u8> = Vec::new();
        recurse(&obj, &start, &mut all, &path, Some(&mut buf), false);
        assert!(buf.is_empty());
        assert!(all.is_empty());
    }
}